Introduction

Contents

Welcome to Setup Factory 9!

Please select one of the following subjects:

What is Setup Factory?

What's New in 9

Key Features

Changes to Setup Factory

Importing Setup Factory 6.0 Projects

The Setup Factory Interface

Are you looking for something else? Perhaps you'll find it in one of these categories:

User's Guide

Scripting Guide

Program Reference

Windows Basics


What is Setup Factory?

Introduction

Contents What is Setup Factory?

Setup Factory is a sophisticated tool that gives you complete control over the installation process. Full-featured, fast, and easy to use, Setup Factory's intuitive design maximizes your ability to deploy software products, data files, graphic images, or anything else that you want to distribute.

Solid and Effective

Setup Factory creates single-file, compact, bulletproof professional software installations. Its visual design environment makes it a snap to assemble your files, customize the wizard interface, add runtime support modules, and package your software for deployment via diskette, CD-ROM, LAN, email or Web.

A Proud Heritage

Since its first release, Setup Factory has defined innovation in Windows based setup and installation tools. Over the years, the product line has been the recipient of numerous awards, accolades and glowing reviews.

Trusted By Professionals

Thousands of software developers trust Setup Factory to distribute their software to millions of customers and clients around the world.

While others have tried to imitate it, only Setup Factory offers such a perfect combination of ease, flexibility and control.


What's New in 9

Introduction

Contents What's New in 9

NEW! Native 64-Bit Runtime

As development of native 64-bit applications continue to grow, take comfort in the fact that Setup Factory has you covered for your distribution needs. Setup Factory now allows you to generate 64-bit setups in addition to 32-bit. Whether you have 64-bit applications ready to go, or just want to be prepared for the future, Setup Factory will be ready and waiting to make your life easier.

NEW! LZMA2 Data Compression

With Setup Factory 9's improved LZMA data compression LZMA2, you'll see remarkably smaller installers as well as faster installation performance than ever before. Take advantage of the power of modern CPUs with its enhanced multithreading support. Compared to previous versions, our test results show up to 300% better compression performance and at least 20% faster installation speed. You'll be able to fit more on each CD/DVD (that’s a potentially huge manufacturing cost savings) and reduce your bandwidth for Internet distributed installers (that saves both you and your customers time and money). Additionally, customers will notice that your installers finish faster - and that means happier customers!

NEW! Faster Building

Every second counts when it comes to development time. Significant improvements have been made to Setup Factory 9's build process meaning that you'll spend less time building and more time developing.

NEW! Faster & More Powerful Lua 5.1 Scripting Engine

Setup Factory's scripting engine is now faster, more powerful and much more extensible. The Lua 5.1 system features incremental garbage collection, new mechanism for varargs, new syntax for long strings and comments, mod and length operators, metatables for all types and a fully reentrant parser.

NEW! Plugin SDK v2

Action Plugins are one of the best features of Setup Factory. They allow 3rd party software developers to extend and expand the product in an extremely integrated and seamless fashion. By simply dropping a plugin into your project, you can easily save yourself hours of work and add significant functionality to your setup. The great news is that with Setup Factory, plugin developers can now fully leverage the advantages of the Lua 5.1 language. The Plugin SDK v2 is available for free download on the indigorose.com website.

NEW! Billboard Screen Control

The new billboard control allows you to incorporate billboards or static images on your custom screens and custom progress screens. Billboards can be used to show both single images, and image slideshows at any point in the setup, even while installing or uninstalling files.

NEW! Custom Progress Screen

Previous progress screen types limited the types of controls you could add. The new custom progress screen gives you the freedom to design your own progress screen with any type or number of controls you wish.

NEW! Custom Screen Size

If screen real estate is important, no need to worry! Setup Factory now allows you to create screens of any size through its enhanced theme settings. Screen sizes can be controlled project-wide through it's theme, or overridden on a per-screen basis.

NEW! Setup Styles / Skinning

Setup Factory 9 gives you the freedom to create setups that look exactly the way you want. Perhaps you prefer that your setups take on the same appearance as the operating system (e.g. Windows XP, Vista, Windows 7 Aero, Windows 8, Windows 8.1, Windows 10)? Or perhaps you'd like to simply make use of the hundreds of ready-to-use MSSTYLES themes (like OS/X Tiger and Panther) that you can download on the Internet? In any case, Setup Factory makes it possible – and easy!

NEW! Set File / Folder Permissions

A powerful new action named "File.SetPermissions" allows you to set the user access permissions of any file or folder on the user's system.

NEW! Enhanced Build Configurations

Building multiple installs from one Setup Factory project has become even easier in Setup Factory 9 with the addition of Dependency Modules and Plugins to build configurations. This helps to make developing 32-bit and 64-bit installations within the same project file a breeze.

NEW! Improved Add Files Dialog

We've improved the Add Files dialog on Windows Vista, Windows 7, Windows 8, Windows 8.1 and Windows 10 to give you the options that you would expect on those operating systems, including the search option and your favorite links.

NEW! Latest Technologies Runtime Dependency Modules

In addition to the classic modules like Visual Basic 5.0/6.0, – Setup Factory now includes easy-to-use runtime dependency modules in both 32-bit and 64-bit for the newest and most popular technologies like .NET 4, Visual C++ 2010 and Windows Installer 4.5.

NEW! 100% Import of Setup Factory 7.0 / 8.0 Projects

Upgrading to Setup Factory 9 is almost completely hassle-free. Simply open up your Setup Factory 7.0 / 8.0 project files and continue development. See the Changes to Setup Factory topic for information about minor changes that may be required.


Key Features

Introduction

Contents Key Features

Setup Factory has been raising the bar for over a decade. It’s fully compatible with Windows XP SP2 through Windows 10. We've added native 64-bit runtime support, additional compression options, updated scripting engine, and enhanced build configuration support. Of course, we're still true to our roots of giving you the easiest to use installer builder available anywhere. But it's now also one of the most powerful solutions as well.

NEW! Native 64-Bit Runtime

As development of native 64-bit applications continue to grow, take comfort in the fact that Setup Factory has you covered for your distribution needs. Setup Factory now allows you to generate 64-bit setups in addition to 32-bit. Whether you have 64-bit applications ready to go, or just want to be prepared for the future, Setup Factory will be ready and waiting to make your life easier.

NEW! LZMA2 Data Compression

With Setup Factory 9's improved LZMA data compression LZMA2, you'll see remarkably smaller installers as well as faster installation performance than ever before. Take advantage of the power of modern CPUs with its enhanced multithreading support. Compared to previous versions, our test results show up to 300% better compression performance and at least 20% faster installation speed. You'll be able to fit more on each CD/DVD (that’s a potentially huge manufacturing cost savings) and reduce your bandwidth for Internet distributed installers (that saves both you and your customers time and money). Additionally, customers will notice that your installers finish faster - and that means happier customers!

NEW! Faster Building

Every second counts when it comes to development time. Significant improvements have been made to Setup Factory 9's build process meaning that you'll spend less time building and more time developing.

NEW! Faster & More Powerful Lua 5.1 Scripting Engine

Setup Factory's scripting engine is now faster, more powerful and much more extensible. The Lua 5.1 system features incremental garbage collection, new mechanism for varargs, new syntax for long strings and comments, mod and length operators, metatables for all types and a fully reentrant parser.

NEW! Plugin SDK v2

Action Plugins are one of the best features of Setup Factory. They allow 3rd party software developers to extend and expand the product in an extremely integrated and seamless fashion. By simply dropping a plugin into your project, you can easily save yourself hours of work and add significant functionality to your setup. The great news is that with Setup Factory, plugin developers can now fully leverage the advantages of the Lua 5.1 language. The Plugin SDK v2 is available for free download on the indigorose.com website.

NEW! Billboard Screen Control

The new billboard control allows you to incorporate billboards or static images on your custom screens and custom progress screens. Billboards can be used to show both single images, and image slideshows at any point in the setup, even while installing or uninstalling files.

NEW! Custom Progress Screen

Previous progress screen types limited the types of controls you could add. The new custom progress screen gives you the freedom to design your own progress screen with any type or number of controls you wish.

NEW! Custom Screen Size

If screen real estate is important, no need to worry! Setup Factory now allows you to create screens of any size through its enhanced theme settings. Screen sizes can be controlled project-wide through it's theme, or overridden on a per-screen basis.

NEW! Setup Styles / Skinning

Setup Factory 9 gives you the freedom to create setups that look exactly the way you want. Perhaps you prefer that your setups take on the same appearance as the operating system (e.g. Windows XP, Vista, Windows 7 Aero, Windows 8, Windows 8.1, Windows 10)? Or perhaps you'd like to simply make use of the hundreds of ready-to-use MSSTYLES themes (like OS/X Tiger and Panther) that you can download on the Internet? In any case, Setup Factory makes it possible – and easy!

NEW! Set File / Folder Permissions

A powerful new action named "File.SetPermissions" allows you to set the user access permissions of any file or folder on the user's system.

NEW! Enhanced Build Configurations

Building multiple installs from one Setup Factory project has become even easier in Setup Factory 9 with the addition of Dependency Modules and Plugins to build configurations. This helps to make developing 32-bit and 64-bit installations within the same project file a breeze.

NEW! Improved Add Files Dialog

We've improved the Add Files dialog on Windows Vista, Windows 7, Windows 8, Windows 8.1 and Windows 10 to give you the options that you would expect on those operating systems, including the search option and your favorite links.

NEW! Latest Technologies Runtime Dependency Modules

In addition to the classic modules like Visual Basic 5.0/6.0, – Setup Factory now includes easy-to-use runtime dependency modules in both 32-bit and 64-bit for the newest and most popular technologies like .NET 4, Visual C++ 2010 and Windows Installer 4.5.

NEW! 100% Import of Setup Factory 7.0 / 8.0 Projects

Upgrading to Setup Factory 9 is almost completely hassle-free. Simply open up your Setup Factory 7.0 / 8.0 project files and continue development. See the Changes to Setup Factory topic for information about minor changes that may be required.

Install Any File – Anywhere!

Setup Factory features an unbeatable development environment that puts you in control of your files. Simply drag and drop your files and folders onto the project window and you're ready to build. Setup Factory is smart enough to maintain your folder structure, automatically query version resource information, create shortcut icons and ensure 100% data integrity with reliable CRC-32 checking. Of course, everything can be customized and overridden if you wish, but for most projects the improved Project Wizard can handle it all with just a few clicks.

Compact Single-File Setups

Smaller and faster means a better experience for your customers and Setup Factory delivers. With no "unpacking" step required, Setup Factory installers are much faster to initialize and install than those created by competitive tools. What's more, our Publishing Wizard walks you through the build process with a few easy steps. The single-file setup.exe is ready for distribution by web, email, LAN, CD and DVD.

Project Quick-Start

Spend five minutes with Setup Factory's easy to use Project Wizard and come away with a complete, ready to build installation project. You'll be walked through each option so you can get your project started as quickly as possible.

Customizable Install Wizard Screens

With a library of more than twenty different screen templates to choose from and a pre-built wizard sequence suitable for the majority of installation tasks, Setup Factory is miles ahead of previous versions and the competition. There are pre-built layouts to handle just about any task your installer could want, and it's easy to adjust them to fit your needs exactly. There's everything from check boxes, radio buttons and edit fields to popular screens like license agreements, serial number verification, shortcut folder selection and other advanced options. The Screen Manager allows you to add and remove screens at will, and adjust the sequence with a simple drag-and-drop motion. Each screen features a real-time preview so you can see the result of your changes as you work.

Themes and Skins

Choose from dozens of pre-made themes (skins) for your screens or even make your own. It's as easy as viewing a live dialog preview and picking your favorite style. You can configure everything from fonts (face, color, size, style) and banner images to body/background graphics, control colors (buttons, check boxes, radio buttons) and more. Whether your installer needs a corporate feel or a hip attitude, you can do it with Setup Factory!

Background Window Options

Choose between the traditional setup-wizard style or the modern Windows Installer style interface. You can customize the background window with gradients, images, color washes, headlines and footer text with 3D effects. Now you can also select a custom taskbar icon, force the setup window to remain on top of other windows or even hide the taskbar icon completely for totally silent installs.

Extensive Action Library

Previous versions of Setup Factory have included a handful of system actions for doing routine tasks such as running programs and creating shortcut icons. Setup Factory takes it to another level and gives you full control over your installer. You get a built-in library of 385 easy to use actions, so you can do whatever you need without having to be an advanced programmer. There are actions to handle everything from text file editing to system registry changes. You can execute programs, call DLL functions, query drive information, manipulate strings, copy files, enumerate processes, start and stop services, interact with web scripts, display dialog boxes and much more.

Easy to Use Action Wizard

You don't have to be a wizard to create powerful installers with Setup Factory. We've built the wizard into the software! Simply choose the action you want from a categorized list (complete with on-screen interactive help), fill in the requested information fields and the wizard does the rest. You don't have to know anything about scripting or programming – just fill in the blanks and you're done. Making changes is just as easy. Click on the line you want to change and press the "edit" button to go back to the original form. It's really that easy.

Powerful Scripting Engine

Setup Factory incorporates an incredibly powerful free-form scripting engine. Based on the popular "LUA" language, this easy to understand scripting language features everything from "for, repeat and while" loops, to "if/else" conditions, functions, variables and tables (associative arrays). Paired with the built-in action library, full mathematical evaluation and Boolean expressions, there's simply nothing you can't achieve. Of course, we've also built in an "Action Wizard" and "Code Wizard" so even complete novices can create powerful installers that handle even the most demanding installation tasks.

Color Syntax Highlighting Action Editor

If you've outgrown the Action Wizard interface or simply want to unleash the power of the fast and efficient scripting engine, we've got you covered. The Setup Factory freeform action editor features all of the professional features you'd expect. There’s color syntax highlighting, code completion, function highlighting, as-you-type action prototypes, Ctrl+Space function listings and even context-sensitive help. If you're used to programming in Microsoft Visual Basic, Microsoft Visual C++ or any other modern development language, you'll be right at home.

Expandable with Action Plugins

Setup Factory can be easily expanded with Action Plugins. These plugin modules can extend the product in infinitely powerful ways, such as adding support for databases and FTP file transfers. Tight integration with the design environment – including IntelliSense style code completion and syntax highlighting – makes them just as easy to use as built-in actions. Plugins are available through Indigo Rose as well as third-party developers thanks to Indigo Rose's freely available plugin development kit.

Dependency Modules & Runtime Support

Instantly add runtime support for many popular third-party technologies, including Visual Basic 5.0, Visual Basic 6.0, .NET 3.0, .NET 3.5, .NET 3.5 SP1, .NET 4, SQL Express 2005, Visual C++ 2008, Visual C++ 2008 SP1, Visual C++ 2010, Windows Installer 3.1 v2, Windows Installer 4.5, and more. Additional dependency modules are easy to create and integrate seamlessly into the development environment. Setup Factory gives you complete control over the detection and installation of each module, so you can easily adjust the behavior to suite your particular requirements.

Flexible Uninstaller

Setup Factory features an uninstall feature. Simply turn it on and let Setup Factory worry about removing your files. Anything that is installed during the setup will be marked for removal by the uninstaller. However, if you want to go in and tinker with the settings, you'll find that the uninstaller is fully customizable. You can take full control of what files are removed, what shortcut icons are deleted, what registry changes are made and anything else you require. Even the dialog screens and sequence can be adjusted to suit your needs!

System Requirements Checking

You can easily enforce system requirements just by clicking a few boxes. Built-in checks include operating system, memory, screen resolution, color depth and administrator privileges. If the user's system does not meet the minimum requirements you have chosen, the installer can either warn the user or abort the setup entirely.

Serial Numbers, Security and Access Features

Setup Factory includes a variety of features designed to help you manage access to your software, including serial number lists and date-based expiration. With its powerful serial number generator you can quickly create thousands of unique serial numbers, which are stored internally as secure MD5 hashes. Hidden from prying eyes, your installer data is compressed using proprietary algorithms and only accessible to those users who supply a valid serial number. Of course, if you'd rather do it yourself, Setup Factory is flexible enough to support your own custom validation and authorization schemes.

Packages, Categories and Install Types

Creating installers for complex and multi-part products is now easier than ever. With dramatically improved support for grouping files into packages, it's a snap to group products and features into a single installer. There's even support for categories so you can group your packages into logical components. It's the ultimate in flexibility for those large projects that need to support different installation types like typical, minimum, complete and custom.

International Language Support

Setup Factory offers unsurpassed support for multilingual installations right out of the box. While some products charge you extra for this essential feature (or don't offer it at all), Setup Factory gives you everything you need to support your customers and clients around the world. Installers created with Setup Factory can automatically determine the language of the client operating system and adjust the display of screens and messages appropriately. Whether you need to support English, French, German, Spanish, Italian or any other language recognized by Windows, with Setup Factory you simply provide the text and your installer takes care of the rest!

Built-in Spelling Checker

It's easier than ever to make sure that typos don't creep into your projects. Basically anywhere you can type, you can perform a spell check to ensure error-free text. Dictionaries are available for over a dozen languages including English, French, German, Italian, Spanish, Dutch, Swedish, Danish, Croatian, Czech, Polish and Slovenian.

Reports and Logs

Keeping track of the essential details of your installation project is now just a couple of clicks away. With improved HTML-based project reports (featuring CSS formatting) and text-based install-time log files, you'll have an accurate record of everything you need. New options let you control the level of detail being logged, including options for recording errors and script actions.

Silent Installs

Create silent installations that operate without displaying user interface dialogs, prompts, messages or errors. Easily read command defaults from a response file and control the installation automatically. Silent installs let you maintain control over hundreds or thousands of workstations while enforcing corporate standards. New options let you enable silent installs with a command line switch, or even force the installer to always run in unattended mode. Setup Factory installers automatically return command line status codes and can be easily called from batch files and automatic build processes.

Visual Basic Project Scanner

If you're creating installers for your Visual Basic projects, then look no further! Setup Factory can analyze your VB project and automatically add the necessary runtime files and dependencies for you. There's even an advanced executable scanner that can assist you in determining required DLL's and libraries for those difficult to manage multi-team projects.

Unattended Builds

Setup Factory fits seamlessly into your daily build process. Creating your product installer every time you build your source code makes it easy to test early and often. Simply include your Setup Factory project in your build process to run automatically and output a finished setup.exe.

Comprehensive User’s Guide

We listened when you said you wanted more learning resources. The user's guide has been written to cover everything you need to know to create professional installers. You'll learn everything from basics like working with files and customizing the user interface all the way up to lessons on mastering the scripting language and creating multilingual installers. It’s sure nice to have when you want to move beyond the wizards and get the most out of your software investment.

Visual Dialog Editor

You have the freedom to create your own custom dialogs from scratch! Start off with an empty wizard dialog and then drop whatever controls you require onto it. Resize them, reposition them, call script code and much more. It's fully featured and totally visual. When one of the built-in dialogs doesn't get you where you want to go, the new visual dialog editor is sure to fit the bill. To use this exciting new feature, look for the "Custom" screen type in the screen gallery.

LZMA Data Compression

With Setup Factory's high performance LZMA data compression, you'll see remarkably smaller installers as well as faster installation performance than ever before. Compared to Setup Factory 7.0, our test results show up to 300% better compression performance and up to 20% faster installation speed. You'll be able to fit more on each CD/DVD (that's a potentially huge manufacturing cost savings) and reduce your bandwidth for Internet distributed installers (that saves both you and your customers time and money). Additionally, customers will notice that your installers finish faster - and that means happier customers!

Custom Setup Icon and Version Resource Info

You can change the embedded setup.exe icon as well as the embedded version resource information (comments, product version, company name, product name, description, trademark, copyright etc.). While other installers force you to display their branding to your customers, Setup Factory gives you the freedom to brand your installer however you see fit.

Automatic Authenticode Signing

It's never been faster or easier to "codesign" your installer executable. Authenticode signing is incredibly important for both Internet downloads and Vista/Windows 7/Windows 8/Windows 8.1/Windows 10 compatibility. Simply point Setup Factory to your certificate and private key files, give it the description information and it will automatically sign your setup.exe during the build process.

Support for Files Larger Than 2GB

Are you distributing massive data files? Setup Factory is up to the challenge. While many installers will choke on files larger than 2GB in size, Setup Factory sails right on through. In fact, with our LZMA data compression, you'll also get dramatically better compression ratios and lightning fast installs.

Custom Error Handling Events

Sometimes things go wrong during install or uninstall. Perhaps the user doesn't have the correct system requirements, or is missing a required application. With Setup Factory you can either let the installer handle it with intelligent defaults, or you can now trigger script code thanks to the "On Install Error" and "On Uninstall Error" events. These events are fired when an error occurs during the setup or uninstall, allowing you to handle it in a custom way.

Plays Well with Source Control

For those of you who prefer to keep your Setup Factory project files in a source control system, we've made it possible to turn off the recording of file time, statistical data, and version information inside the project file. This makes it much easier to add Setup Factory project files to source control and not trigger immaterial "changes".

Stand Alone Script Editor

Setup Factory includes the Indigo Rose Script Editor application. This stand-alone program allows you to edit your installer scripts outside of the Setup Factory IDE. Includes support for syntax highlighting, intellisense code completion and help file integration. Simply run "IRScriptEditor.exe" from the Setup Factory program folder.


Changes to Setup Factory

Introduction

Contents Changes to Setup Factory

Full Support for v7 and v8 Projects

Setup Factory 9 remains almost 100% compatible with v7 and v8 projects. The items below describe areas that may require attention.

Lua Language Changes

Setup Factory now contains an updated version of the Lua scripting library, version 5.1 (previously 5.0). Setup Factory's version has been compiled to try to maintain compatibility, however there are some minor syntax changes/deprecations made to the language that you need to be aware of for future development as well as previously created projects and lua scripts.

When importing a project made with an earlier version of Setup Factory, Setup Factory 9 will automatically analyze your project file and create a report detailing any areas where it thinks the old style for loop is in use. If there are any old for loops found the report will automatically be saved in the same folder as your new 9 project file and opened in your default web-browser. We recommend analyzing each line of code found in the report to ensure that you only use the new for loop syntax.

Table Iterating For Loops

The syntax for iterating a table using for loop using in has changed (has been deprecated) If the syntax is not changed, a runtime error will be thrown when executed.

Old syntax:

mytable = {"One","Two","Three"};

for k, v in mytable do
Dialog.Message("Table Item", k .. "=" .. v);
end -- for

Needs to be changed to:

mytable = {"One","Two","Three"};

for k, v in pairs (mytable) do
Dialog.Message("Table Item", k .. "=" .. v);
end -- for

The functions table.foreach and table.foreachi are also deprecated. You can use a for loop as above with pairs or ipairs instead. While these two are deprecated, they still work (unlike the example above), however you are advised to also rework these types of loops in case they are removed from future versions.

If you commonly use Lua functions (non-Setup Factory actions) in your scripts, you may also want to review the list of other changes to the language in case other changes affect you. You can find this information in the Lua 5.1 Reference Manual found on http://www.lua.org.

Plugin Changes

As of Setup Factory 9, only action plugins created with version 2 of the Plugin SDK (or higher) are compatible. When a version 7 or 8 project is opened in version 9, the project is analyzed to determine if it contains any plugin actions. A list of these can be viewed in the analysis report that is automatically generated under the heading "Legacy Plugins."

In order for your project to work you will need to obtain updated versions of the plugins listed. Once you have the updated version of these plugins, simply install them into the correct plugin directory and your project should work properly. If you have already installed versions of the listed plugins that were created using version 2 of the Indigo Rose Plugin SDK then no further action is necessary.

Supported Operating System Changes

With the diminishing user base of older operating systems, and benefits of using the latest development tools and compilers on the market, Setup Factory's operating system requirements have changed for version 9. The minimum supported operating system for both design and runtime is now Windows XP SP2. Unsupported operating systems will receive the standard "not a valid Win32 application" error message.

Compression Changes

The previous "Setup Factory 7.0" compression option has been replaced by a new LZMA2 compression option. Both LZMA compression options outperform previous compression in all aspects.


Importing Setup Factory 6.0 Projects

Overview What Is Converted What Is Not Converted (Gotcha's) Converting Actions

This topic serves as an introduction to the project conversion process from Setup Factory 6.0 to Setup Factory 9. It will describe what the project converter can and cannot convert. It will also explain the reasons behind the decisions made and what to do once your Setup Factory 6.0 project has been converted to Setup Factory 9.

Introduction

Setup Factory 7.0 was rebuilt from the ground up to be infinitely more powerful and flexible than previous versions. As such, it required an entirely new "scripting engine" to process actions. This also means that an exact and automated one-to-one conversion of actions from the v6.0 format is impossible. Another significant change is the new format used for screens. While there are many benefits to the new screen design such as the ability to theme your install, multilingual installs have never been easier to manage. Instead of having to include a new screen for each language in your install, you can now manage all language translations on each screen.

As a result, the conversion of projects created with v6.0 is not a fully automated process. In general, your file listings and many other project settings will be converted automatically, while your script actions and screens must be converted by hand.

Converting Projects from v6.0 to v9

Given the changes to the scripting engine, the decision you'll need to make is whether or not to convert your v6.0 projects to v9 projects. Ultimately, the choice is up to you. You'll certainly want to create all of your new projects using v9 - it's just so much better and more powerful. It's whether or not it's worth it to you or your company/client to “upgrade” your v6.0 projects to take advantage of v9 features.

In many cases, the answer will be to leave your already working v6.0 projects the way they are and then shift your new development to v9.

That being said, it's not a complicated process to convert your v6.0 projects to the new v9 platform, but it may be time-consuming to recreate your actions and screens in v9 if you have a particularly complicated project. Of course, it doesn't hurt to try and see what's involved. Simply go to File > Open and select a v6.0 (*.sf6) project. The conversion tool will take over and do its best to create a v9 compatible project from your v6.0 source. Take a look at the resulting project and decide for yourself. If any warnings or errors occur, they can be seen in the output panel.

Where Do I Go Next?

You'll definitely want to read the rest of the topic, including the What Is Converted and What is Not Converted (Gotcha's) sections. That'll give you an exact rundown of what to expect from the automated conversion process. Another topic you may want to consult is the Converting Actions topic that lists version 6.0's actions and their version 9 equivalents. Then you'll want to become more familiar with all of the goodies you'll find in v9. They'll make your projects cooler and more professional!

The first section to read in the help file should be the Key Features section. This will help point out all of the new and exciting features available in version 9. The next section to take a look at is the topic The Setup Factory Interface. This will provide a brief tour of the design environment so you are familiar with the terms used throughout the rest of the documentation.

If you are still not sure how things work in Setup Factory 9, the User’s Guide is an indispensable tool. It is a topical task based manual describing the features and use of the product. It was written in such a way that you can simply jump to the sections that you need to learn at that moment.

If you think that you have a good handle on what "the Setup Factory 9" way entails, but are looking for some specific real world examples, look no further than the Examples section of our forums at http://www.indigorose.com/forums. This area provides various articles answering some of the most common questions we have been asked about Setup Factory.

At this point you should know almost everything there is to know about Setup Factory 9, so it’s time to translate your Setup Factory 6.0 actions into Setup Factory 9 scripts, and recreate your screens. For your convenience all of the actions (except screen actions) you created in your Setup Factory 6.0 project have been imported into Setup Factory 9 as comments on the events that they were originally intended for.

Before attempting to translate your actions into Setup Factory 9 scripts, you should read over the Scripting Guide located in the Help file. This guide will provide you with tips, tricks, and professional-level techniques you should use when writing your Setup Factory 9 scripts.


The Setup Factory Interface

Introduction

Contents The Setup Factory Interface

The Setup Factory program window is divided into a number of different parts.

At the top of the window, just under the title bar, is the program menu. You can click on this program menu to access various commands, settings and tools.

Below the program menu are a number of toolbars. The buttons on these toolbars give you easy access to many of the commands that are available in the program menu.

Tip: You can create your own custom toolbars or edit the existing ones by choosing Tools > Customize.

Most of the program window is taken up by the file list, which is where all the files in your project are listed. There are actually two file lists—one for files that are packed into the setup executable's data archive, and one for external files that are distributed along with your setup executable. You can switch between the Archive file list and the External file list by clicking on their respective tabs.

At the very bottom of the window, a status bar reflects your interaction with the program and offers a number of informative readouts.

The rest of the program window is made up of individual sub-windows known as panes. Each pane can be docked, tabbed, pinned, resized, dragged, and even made to float on top of the design environment.

Tip: For more information on Setup Factory's design interface, see Chapter 1 - "Getting Started" in the Setup Factory User's Guide.


Introduction

User's Guide - Introduction

Introduction

Setup Factory has been raising the bar for over a decade. It's compatible with Windows XP SP2 through Windows 10. We've added native 64-bit runtime support, additional compression options, updated scripting engine, and enhanced build configuration support. Of course, we're true to our roots; we still make the easiest to use installer builder available anywhere. But now, it's one of the most powerful solutions as well.

What is Setup Factory?

Setup Factory is a sophisticated tool that gives you complete control over the installation process. Full-featured, fast, and easy to use, Setup Factory's intuitive design maximizes your ability to deploy software products, data files, graphic images, or anything else that you want to distribute.

Creates Compact and Reliable Software Installers

Setup Factory creates single-file, compact, and bulletproof professional software installations. Its visual design environment makes it a snap to assemble your files, customize the wizard interface, add runtime support modules, and package your software for deployment via diskette, CD-ROM, LAN, email or Web.

A Proud Heritage

Since its first release, Setup Factory has defined innovation in Windows based setup and installation tools. Over the years, the product line has been the recipient of numerous awards, accolades and glowing reviews.

Trusted by Professionals

Thousands of software developers trust Setup Factory to distribute their software to millions of customers and clients around the world.

While others have tried to imitate it, only Setup Factory offers such a perfect combination of ease, flexibility and control.

Key Features in Setup Factory

NEW! Native 64-Bit Runtime

As development of native 64-bit applications continue to grow, take comfort in the fact that Setup Factory has you covered for your distribution needs. Setup Factory now allows you to generate 64-bit setups in addition to 32-bit. Whether you have 64-bit applications ready to go, or just want to be prepared for the future, Setup Factory will be ready and waiting to make your life easier.

NEW! LZMA2 Data Compression

With Setup Factory 9's improved LZMA data compression LZMA2, you'll see remarkably smaller installers as well as faster installation performance than ever before. Take advantage of the power of modern CPUs with its enhanced multithreading support. Compared to previous versions, our test results show up to 300% better compression performance and at least 20% faster installation speed. You'll be able to fit more on each CD/DVD (that’s a potentially huge manufacturing cost savings) and reduce your bandwidth for Internet distributed installers (that saves both you and your customers time and money). Additionally, customers will notice that your installers finish faster - and that means happier customers!

NEW! Faster Building

Every second counts when it comes to development time. Significant improvements have been made to Setup Factory 9's build process meaning that you'll spend less time building and more time developing.

NEW! Faster & More Powerful Lua 5.1 Scripting Engine

Setup Factory's scripting engine is now faster, more powerful and much more extensible. The Lua 5.1 system features incremental garbage collection, new mechanism for varargs, new syntax for long strings and comments, mod and length operators, metatables for all types and a fully reentrant parser.

NEW! Plugin SDK v2

Action Plugins are one of the best features of Setup Factory. They allow 3rd party software developers to extend and expand the product in an extremely integrated and seamless fashion. By simply dropping a plugin into your project, you can easily save yourself hours of work and add significant functionality to your setup. The great news is that with Setup Factory, plugin developers can now fully leverage the advantages of the Lua 5.1 language. The Plugin SDK v2 is available for free download on the indigorose.com website.

NEW! Billboard Screen Control

The new billboard control allows you to incorporate billboards or static images on your custom screens and custom progress screens. Billboards can be used to show both single images, and image slideshows at any point in the setup, even while installing or uninstalling files.

NEW! Custom Progress Screen

Previous progress screen types limited the types of controls you could add. The new custom progress screen gives you the freedom to design your own progress screen with any type or number of controls you wish.

NEW! Custom Screen Size

If screen real estate is important, no need to worry! Setup Factory now allows you to create screens of any size through its enhanced theme settings. Screen sizes can be controlled project-wide through it's theme, or overridden on a per-screen basis.

NEW! Setup Styles / Skinning

Setup Factory 9 gives you the freedom to create setups that look exactly the way you want. Perhaps you prefer that your setups take on the same appearance as the operating system (e.g. Windows XP, Vista, Windows 7 Aero, Windows 8, Windows 8.1, Windows 10)? Or perhaps you'd like to simply make use of the hundreds of ready-to-use MSSTYLES themes (like OS/X Tiger and Panther) that you can download on the Internet? In any case, Setup Factory makes it possible – and easy!

NEW! Set File / Folder Permissions

A powerful new action named "File.SetPermissions" allows you to set the user access permissions of any file or folder on the user's system.

NEW! Enhanced Build Configurations

Building multiple installs from one Setup Factory project has become even easier in Setup Factory 9 with the addition of Dependency Modules and Plugins to build configurations. This helps to make developing 32-bit and 64-bit installations within the same project file a breeze.

NEW! Improved Add Files Dialog

We've improved the Add Files dialog on Windows Vista, Windows 7, Windows 8, Windows 8.1 and Windows 10 to give you the options that you would expect on those operating systems, including the search option and your favorite links.

NEW! Latest Technologies Runtime Dependency Modules

In addition to the classic modules like Visual Basic 5.0/6.0, – Setup Factory now includes easy-to-use runtime dependency modules in both 32-bit and 64-bit for the newest and most popular technologies like .NET 4, Visual C++ 2010 and Windows Installer 4.5.

NEW! 100% Import of Setup Factory 7.0 / 8.0 Projects

Upgrading to Setup Factory 9 is almost completely hassle-free. Simply open up your Setup Factory 7.0 / 8.0 project files and continue development. See the Changes to Setup Factory topic for information about minor changes that may be required.

Install Any File – Anywhere!

Setup Factory features an unbeatable development environment that puts you in control of your files. Simply drag and drop your files and folders onto the project window and you’re ready to build. Setup Factory is smart enough to maintain your folder structure, automatically query version resource information, create shortcut icons and ensure 100% data integrity with reliable CRC-32 checking. Of course, everything can be customized and overridden if you wish, but for most projects the improved Project Wizard can handle it all with just a few clicks.

Compact Single-File Setups

Smaller and faster means a better experience for your customers and Setup Factory delivers. With no "unpacking" step required, Setup Factory installers are much faster to initialize and install than those created by competitive tools. What’s more, our Publishing Wizard walks you through the build process with a few easy steps. The single-file setup.exe is ready for distribution by web, email, LAN, CD and DVD.

Project Quick-Start

Spend five minutes with Setup Factory's easy to use Project Wizard and come away with a complete, ready to build installation project. You'll be walked through each option so you can get your project started as quickly as possible.

Customizable Install Wizard Screens

With a library of more than twenty different screen templates to choose from and a pre-built wizard sequence suitable for the majority of installation tasks, Setup Factory is miles ahead of both previous versions and the competition. There are pre-built layouts to handle just about any task your installer could want, and it’s easy to adjust them to fit your needs exactly. There's everything from check boxes, radio buttons and edit fields to popular screens like license agreements, serial number verification, shortcut folder selection and other advanced options. The Screen Manager allows you to add and remove screens at will and adjust the sequence with a simple drag-and-drop motion. Each screen features a real-time preview so you can see the result of your changes as you work.

Themes and Skins

Choose from dozens of pre-made themes (skins) for your screens or even make your own. It's as easy as viewing a live dialog preview and picking your favorite style. You can configure everything from fonts (face, color, size, style) and banner images to body/background graphics, control colors (buttons, check boxes, radio buttons) and more. Whether your installer needs a corporate feel or a hip attitude, you can do it with Setup Factory!

Background Window Options

Choose between the traditional setup-wizard style or the modern Windows Installer style interface. You can customize the background window with gradients, images, color washes, headlines and footer text with 3D effects. Now you can also select a custom taskbar icon, force the setup window to remain on top of other windows or even hide the taskbar icon completely for totally silent installs.

Extensive Action Library

Previous versions of Setup Factory have included a handful of system actions for doing routine tasks such as running programs and creating shortcut icons. Setup Factory takes it to another level and gives you full control over your installer. You get a built-in library of 385 easy to use actions, so you can do whatever you need without having to be an advanced programmer. There are actions to handle everything from text file editing to system registry changes. You can execute programs, call DLL functions, query drive information, manipulate strings, copy files, enumerate processes, start and stop services, interact with web scripts, display dialog boxes and much more.

Easy to Use Action Wizard

You don't have to be a wizard to create powerful installers with Setup Factory. We've built the wizard into the software! Simply choose the action you want from a categorized list (complete with on-screen interactive help), fill in the requested information fields and the wizard does the rest. You don't have to know anything about scripting or programming – just fill in the blanks and you're done. Making changes is just as easy. Click on the line you want to change and press the "edit" button to go back to the original form. It's really that easy.

Powerful Scripting Engine

Setup Factory incorporates an incredibly powerful free-form scripting engine. Based on the popular LUA language, this easy to understand scripting language features everything from "for, repeat and while" loops, to "if/else" conditions, functions, variables and tables (associative arrays). Paired with the built-in action library, full mathematical evaluation and Boolean expressions, there's simply nothing you can't achieve. Of course, we've also built in an "Action Wizard" and "Code Wizard" so even complete novices can create powerful installers that handle even the most demanding installation tasks.

Color Syntax Highlighting Action Editor

If you've outgrown the Action Wizard interface or simply want to unleash the power of the fast and efficient scripting engine, we've got you covered. The Setup Factory freeform action editor features all of the professional features you'd expect. There's color syntax highlighting, code completion, function highlighting, as-you-type action prototypes, Ctrl+Space function listings and even context-sensitive help. If you're used to programming in MicrosoftÒ Visual Basic, MicrosoftÒ Visual C++ or any other modern development language, you'll be right at home.

Expandable with Action Plugins

Setup Factory can be easily expanded with Action Plugins. These plugin modules can extend the product in infinitely powerful ways, such as adding support for databases and FTP file transfers. Tight integration with the design environment – including IntelliSense style code completion and syntax highlighting – makes them just as easy to use as built-in actions. Plugins are available through Indigo Rose as well as third-party developers thanks to Indigo Rose's freely available plugin development kit.

Dependency Modules & Runtime Support

Instantly add runtime support for many popular third-party technologies, including Visual Basic 5.0, Visual Basic 6.0, .NET 3.0, .NET 3.5, .NET 3.5 SP1, .NET 4, SQL Express 2005, Visual C++ 2008, Visual C++ 2008 SP1, Visual C++ 2010, Windows Installer 3.1 v2, Windows Installer 4.5, and more. Additional dependency modules are easy to create and integrate seamlessly into the development environment. Setup Factory gives you complete control over the detection and installation of each module, so you can easily adjust the behavior to suite your particular requirements.

Flexible Uninstaller

Setup Factory features a powerful uninstall feature. Simply turn it on and let Setup Factory worry about removing your files. Anything that is installed during the setup will be marked for removal by the uninstaller. However, if you want to go in and tinker with the settings, you'll find that the uninstaller is fully customizable. You can take full control of what files are removed, what shortcut icons are deleted, what registry changes are made and anything else you require. Even the dialog screens and sequence can be adjusted to suit your needs!

System Requirements Checking

You can easily enforce system requirements just by clicking a few boxes. Built-in checks include operating system, memory, screen resolution, color depth and administrator privileges. If the user's system does not meet the minimum requirements you have chosen, the installer can either warn the user or abort the setup entirely.

Serial Numbers, Security and Access Features

Setup Factory includes a variety of features designed to help you manage access to your software, including serial number lists and date-based expiration. With its powerful serial number generator you can quickly create thousands of unique serial numbers, which are stored internally as secure MD5 hashes. Hidden from prying eyes, your installer data is compressed using proprietary algorithms and only accessible to those users who supply a valid serial number. Of course, if you'd rather do it yourself, Setup Factory is flexible enough to support your own custom validation and authorization schemes.

Packages, Categories and Install Types

Creating installers for complex and multi-part products is easier than ever. It's a snap to group products and features into a single installer. There's even support for categories so you can group your packages into logical components. It's the ultimate in flexibility for those large projects that need to support different installation types like typical, minimum, complete and custom.

International Language Support

Setup Factory offers unsurpassed support for multilingual installations right out of the box. While some products charge you extra for this essential feature (or don't offer it at all), Setup Factory gives you everything you need to support your customers and clients around the world. Installers created with Setup Factory can automatically determine the language of the client operating system and adjust the display of screens and messages appropriately. Whether you need to support English, French, German, Spanish, Italian or any other language recognized by Windows, with Setup Factory you simply provide the text and your installer takes care of the rest!

Built-in Spelling Checker

It's never been easier to make sure that typos don't creep into your projects. Basically anywhere you can type, you can perform a spell check to ensure error-free text. Dictionaries are available for over a dozen languages including English, French, German, Italian, Spanish, Dutch, Swedish, Danish, Croatian, Czech, Polish and Slovenian.

Reports and Logs

Keeping track of the essential details of your installation project is just a couple of clicks away. With HTML-based project reports (featuring CSS formatting) and text-based install-time log files, you'll have an accurate record of everything you need. New options let you control the level of detail being logged, including options for recording errors and script actions.

Silent Installs

Create silent installations that operate without displaying user interface dialogs, prompts, messages or errors. Easily read command defaults from a response file and control the installation automatically. Silent installs let you maintain control over hundreds or thousands of workstations while enforcing corporate standards. New options let you enable silent installs with a command line switch, or even force the installer to always run in unattended mode. Setup Factory installers automatically return command line status codes and can be easily called from batch files and automatic build processes.

Visual Basic Project Scanner

If you're creating installers for your Visual Basic projects, then look no further! Setup Factory can analyze your VB project and automatically add the necessary runtime files and dependencies for you. There's even an advanced executable scanner that can assist you in determining required DLLs and libraries for those difficult to manage multi-team projects.

Unattended Builds

Setup Factory fits seamlessly into your daily build process. Creating your product installer every time you build your source code makes it easy to test early and often. Simply include your Setup Factory project in your build process to run automatically and output a finished setup.exe.

About this Guide

This user's guide is intended to teach you the basic concepts you need to know in order to build a working installer. You'll learn the ins and outs of the program interface and how to perform many common tasks.

The guide is organized into 11 chapters:

Chapter 1: Getting Started
Chapter 2: Working with Files
Chapter 3: Creating the User Interface
Chapter 4: Actions, Scripts and Plugins
Chapter 5: Session Variables
Chapter 6: Packages
Chapter 7: Languages
Chapter 8: Security and Expiration
Chapter 9: Dependencies
Chapter 10: Uninstall
Chapter 11: Building and Distributing

Each chapter begins with a brief overview and a list of the things you will learn in that chapter.

Document Conventions

This user's guide follows some simple rules for presenting information such as keyboard shortcuts and menu commands.

Keyboard Shortcuts

Keyboard shortcuts are described like this: press Ctrl+V. The "+" means to hold the Ctrl key down while you press the V key.

Menu Commands

Menu commands are described like this: choose File > Open. This means to click on the File menu at the top of the Setup Factory program window, and then click on the Open command in the list that appears.

Click on the File menu... ...and click on the Open command

Typed-In Text

When you're meant to type something into a text field, it will be presented in italics, like this: type "Setup Factory makes me happy" into the Message setting. This means to type in "Setup Factory makes me happy", including the quotes.


Chapter 1: Getting Started

Getting Started

Every journey begins with a first step. In this chapter, we'll walk you through the creation of a new project and introduce you to the Setup Factory program interface.

In This Chapter

In this chapter, you'll learn about:

• Starting a new project

• Making sure you have the latest version

• Learning the interface

• Getting help

• Setting preferences

• Planning your installation

Starting a New Project

Everything has to start somewhere. In Setup Factory, the design process starts with the creation of a new project.

A project is simply the collection of files and settings and everything else that goes into building an installer. A typical project will contain all of the files that you want to distribute, some screens that inform or gather information from the user, and maybe a few actions to take care of any extras (such as storing the installation path in a registry key for future use by your patching tools).

The project file

Each file that you add to a Setup Factory project has individual settings that control where, when and how the file will be installed at run time. Likewise, each screen that you can display has its own properties that determine everything from the text that appears on the various parts of the screen to the color of the screen itself.

These settings are all stored in a single file called the project file. The project file contains all of the properties and settings of a project and the list of source files that need to be gathered up each time the project is built.

The project file is automatically created for you when you start a new project.

When you start a new project, Setup Factory's project wizard walks you through the first few steps of project creation. This helps you get your project started quickly without missing any of the basics.

Lets open the Setup Factory program and start a new project.

1) Open Setup Factory.

Use the Start menu to launch the Setup Factory program.

You'll find Setup Factory under:

Start > Programs > Indigo Rose Corporation > Setup Factory 9

2) When the Welcome dialog appears, click on Create a new project.

The Welcome dialog appears whenever you run Setup Factory. It not only welcomes you to the program; it also lets you easily create a new project or open an existing one

When you click on Create a new project, the Welcome dialog closes and the project wizard appears.

3) Enter your information and click Next.

The first step of the project wizard asks you for four pieces of information related to your project. Simply enter your company name, product name, product version, and web address into the appropriate fields.

When you've entered all your information, click Next to move to the next step in the project wizard.

Tip: At any step in the project wizard, you can click Cancel to go straight to the program window with no files added and all of the default settings untouched. If you find that you don't use the project wizard, and want something a little more permanent than clicking Cancel, you can uncheck the Show Project Wizard checkbox in the Start a New Project dialog. Turning off that option will make Setup Factory open a blank project all the time, without showing you the project wizard. For now though, leave this option turned on so you can see what the project wizard contains.

4) Select the desired platform, and click Next.

The next step in the project wizard is to specify the desired platform of your setup. This decision should be made based on the platform (either 32-bit or 64-bit) of the application or files you are distributing. This setting can be changed at any time in the build settings.

When you've made a selection, click Next to move to the next step in the project wizard.

5) Provide the full path of the folder where your files are located, and click Next.

The next step in the project wizard is to specify the folder where your source files are located.

Note: In this case, source files refers to the original files on your local hard drive, i.e. the files that you want to create an installer for, and not files containing source code. Setup Factory doesn't need access to your source code files at all (unless you intend to distribute them in your installer).

Tip: You can use the Browse button to browse for a folder.

If your product files are spread across several folders, choose the main folder that represents the core of your product. By default, all of the files and folders contained within the folder that you select will be included as well, so you want to choose the folder at the top of your product's folder hierarchy.

Once you've selected the folder, click Next to proceed to the next step.

6) Select a style for your setup application window, and click Next.

This step determines whether or not your installer will have a background window behind it covering the users desktop.

Note: If you choose to have a background window, you can customize its appearance using the settings in this project wizard step.

Once you've selected your window style, click Next to proceed to the next step.

7) Select a visual theme for your installers interface, and click Next.

Setup Factory has support for project themes. Project themes are a set of visual attributes that are applied to all of the screens in your installer to give them a uniform look and feel. These attributes include color, banner styles, images, fonts, and more. You can change the look throughout your entire installer by simply switching to a different theme.

Below the theme selector, a preview image shows what a sample screen would look like with the theme applied.

Note: The selected theme will be applied to all screens in your project. However, you can override the theme settings on a per-screen basis using the Override project theme option on each screens Style tab.

Feel free to try out some of the different themes. Once you've picked one that you like, click Next to proceed to the next step in the project wizard.

8) Select the languages that you plan to support in your installer, and click Next.

The Multilingual Settings step of the project wizard asks you to select the languages that you want your installer to support. Every language in the list that has a checkmark next to it will be supported in your setup.

Two things happen when a language is supported. First, Setup Factory will use the text from that language's message file (if one exists) for the installers built-in messages when that language is detected at run time. (If a message file doesn't exist for a particular message, the default languages message file will be used.)

Second (and more important), you will be able to localize the text in your project for each supported language. For example, if you choose English, French and German as your three supported languages, you will be able to enter different English, French and German text on your projects screens, package descriptions, etc. This is done by simply choosing a different language from the language selector that appears wherever there is text that you can translate in your project.

Note: Supporting a language adds it to the list of languages available in the language selector.

Once you've selected the languages you want to support, click Next to proceed to the next step.

9) Select any technologies that your product requires, and click Next.

If your product has any requirements, such as the Visual Basic or .NET runtime, select them in the list. Setup Factory will automatically check for the selected technologies at run time and will require the user to install them before performing the installation.

Select your product's requirements in the list, and click Next to proceed to the final step.

10) Select the optional features you want, and select the operating systems that your product will work on. Once you're ready, click Finish to apply your settings to your new project.

The final step of the project wizard lets you configure a number of optional features, such as whether to automatically provide an uninstaller, and whether to alert the user if they attempt to install without Administrative privileges. (Usually you'll want to leave all of these features turned on.)

You can also configure the operating system requirements for your project. Setup Factory will automatically limit the installer to only perform the installation on operating systems that are selected (checked) in this list. So, for example, if you do not want anyone to install your software on Windows XP, simply turn off support for that operating system, and the installer will automatically abort (with a short explanation) when its run on that OS.

When you click Finish, the project wizard closes and the new project is loaded into the design environment with the settings you chose.

Note: The Setup Factory program interface is also known as the design environment.

If you selected a folder with files in it in step 5, those files will automatically be added to the file list for you.

At this point, you could build the project and generate a basic installer for those files. Of course, you'd probably want to customize the screens before distributing it. To learn how to customize the screens in your installer, see Chapter 3.

Tip: Once you're in the design environment, you can start a new project by choosing File > New.

11) Maximize the Setup Factory program window.

The easiest way to work with Setup Factory is with the program window maximized so it covers the whole screen. This way, you have the whole desktop area to work with, and you wont have any other programs or windows in the background to distract you.

To maximize the window, click on the little Maximize button, which is the second button from the right on the Setup Factory title bar (right next to the Close button).

If the maximize button looks like this:

...it means you already have the program window maximized. (That button is actually the Restore button, which takes the place of the Maximize button while the window is maximized. If you click the Restore button, the window will return to the size and position it had before you maximized it.)

Making Sure You Have the Latest Version

As with any application, Setup Factory will from time to time be updated to include bug fixes and possibly new features. In order to ensure you have the most current version of Setup Factory installed, you can check for updates by choosing Help > Check for Update from the program menu.

Note: Setup Factory will automatically prompt you to check for updates every 30 days by default. You can modify this value at any time through the Preferences dialog (Edit > Preferences)

Tip: To include this type of functionality in your software application, check out TrueUpdate (www.indigorose.com) today!

Learning the Interface

Now that you have Setup Factory started and you've made sure that you're using the latest version, its time to get comfortable with the program interface itself.

1) Explore the Setup Factory program window.

The Setup Factory program window is divided into a number of different parts.

At the top of the window, just under the title bar, is the program menu. You can click on this program menu to access various commands, settings and tools.

Below the program menu are a number of toolbars. The buttons on these toolbars give you easy access to many of the commands that are available in the program menu.

Tip: You can create your own custom toolbars or edit the existing ones by choosing Tools > Customize.

Most of the program window is taken up by the file list, which is where all the files in your project are listed. There are actually two file lists - one for files that are packed into the setup executables data archive, and one for external files that are distributed along with your setup executable. You can switch between the Archive file list and the External file list by clicking on their respective tabs.

At the very bottom of the window, a status bar reflects your interaction with the program and offers a number of informative readouts.

The rest of the program window is made up of individual sub-windows known as panes. Each pane can be docked, tabbed, pinned, resized, dragged, and even made to float on top of the design environment.

The long horizontal pane near the bottom of the program window (just above the status bar) is the output pane (which isn't visible by default). This is where Setup Factory displays the progress of lengthy operations, such as report generation, project conversion, and building the project (unless the publish wizard is being used, since it has its own output window).

The tall pane on the left is the task pane. The task pane provides easy access to the parts of Setup Factory you will use the most. It provides an alternative to the program menu for accessing the various parts of the Setup Factory design environment.

The items on the task pane are organized into categories. You can expand or collapse these categories by clicking on the category heading.

2) Close the task pane.

You can close a pane by clicking on the little x on its title bar.

3) Choose View > Tasks to open the task pane again.

All of the panes can be toggled on or off in the View menu. When you choose View > Tasks, the task pane is restored to the same position it occupied before you closed it.

4) Make the output pane taller by dragging its top edge up.

First, make the output pane visible by choosing View > Output. You can resize panes by dragging their edges. In this case, you want to drag the part between the output pane and the file list...specifically, the little bit of window surface below the file list and above the output panes title bar. As you begin to drag the edge of a pane, a line will appear to show where the edge will move to when you release the mouse button.

When panes are docked alongside each other, dragging an edge will resize both panes at the same time. As you make the output pane taller, you will be making the file list shorter at the same time.

5) Double-click on the output panes title bar to un-dock it.

The output pane is docked by default. A docked pane is seamlessly integrated into the program window. You can un-dock it from the program window by double-clicking on its title bar.

When you un-dock the output pane, it floats above the program window, and the file list expands to fill in the space that the output pane left behind.

6) Drag the output pane to the bottom edge of the program window to dock it again.

You can move panes around by dragging them by their title bars. As you move a pane, an outline shows you the general area where the panel will end up. If you drag the pane near the edge of the program window, or near another pane, the outline will snap to show you how the pane can be docked, tabbed, or otherwise combined with the target area.

Tip: When you're dragging panes, its the position of the mouse cursor that determines where the outline snaps into place. For example, to dock a pane below another one, drag the pane so the cursor is near the bottom edge of that pane. To tab one pane with another, drag the pane so the cursor is on top of the other panes title bar.

Docked panes can also be pinned or unpinned. Pinned panes remain open when you're not using them. (All of the panes in the default layout are pinned.) Unpinned panes stay out of the way until you click on them or hover the mouse over them. Whenever you need them they slide open, on top of everything else, and then slide closed when you're done.

The task pane unpinned... ...and after "sliding" open

You can pin or unpin a pane by clicking the little pin icon on the panes title bar.

Panes remember their positions even after you unpin them. If you unpin a pane, and then pin it again, it will return to the position it had before it was unpinned.

Getting Help

If you still have questions after reading the users guide, there are many self-help resources at your disposal.

Here are some tips on how to quickly access these self-help resources.

1) Press the F1 key.

The online help is only a key press away! Setup Factory comes with an extensive online program reference with information on every object, action, and feature in the program.

In fact, whenever possible, pressing F1 will actually bring you directly to the appropriate topic in the online help. This context-sensitive help is an excellent way to answer any questions you may have about a specific dialog or object.

Note: You can also access the online help system by choosing Help > Setup Factory Help.

There are three ways to navigate the online help system: you can find the appropriate topic using the table of contents, or with the help of the keyword index, or by searching through the entire help system for a specific word or phrase.

2) Close the online help window and return to the Setup Factory design environment.

To exit from the online help, just click the Close button on the help windows title bar.

3) Choose Help > User Forums.

Setup Factory is used by thousands of people worldwide. Many users enjoy sharing ideas and tips with other users. The online forums can be an excellent resource when you need help with a project or run into a problem that other users may have encountered.

Choosing Help > User Forums opens your default web browser directly to the online user forums at the Indigo Rose web site.

4) Close your web browser and return to the Setup Factory design environment.

Exit from your web browser and switch back to the Setup Factory program.

Alternatively, you can press Alt+Tab to switch back to Setup Factory while leaving the web browser open in the background.

5) Choose Help > Technical Support.

This takes you to the Indigo Rose web site, where a variety of online technical support resources are available to you.

This is also where you can find information about ordering one of our premium support packages and submitting a support request.

6) Close your web browser and return to the Setup Factory design environment.

When you're done browsing the technical support information, return to the Setup Factory design environment to continue with this chapter.

Setting Preferences

There are a number of preferences that you can configure to adjust the Setup Factory design environment to suit your work style. Lets have a look at some of them.

1) Choose Edit > Preferences.

This will open the Preferences dialog, where all of Setup Factory's preferences can be found.

The preferences are arranged into categories. The categories are listed on the left side of the dialog. When you click on a category, the corresponding preferences appear on the right side of the dialog.

2) Click on the Document category.

The Document preferences allow you to change settings that affect the project file. For example, you can configure the auto-save feature that can automatically save your project file as you're working on it to avoid any accidental loss of data. You can also configure the number of undo/redo levels, and choose either to use the project wizard to create new projects or to simply start with a new, blank project.

Tip: It can be helpful to set the number of undo levels to a larger value, like 25 or 50. That way you can undo even more steps back if you change your mind while you're working on a project.

3) Expand the Environment category by double-clicking on it, and then click on the Folders category.

You can also expand the Environment category by clicking on the little plus symbol to the left of it.

The Folders category allows you to specify the locations of various folders that are used by the project. For example, you can specify the location of the project folder (where project files are stored) and the default output folder (where setup executables are built to by default).

4) Feel free to explore some of the other categories. When you're done, click OK to close the Preferences dialog.

There are many other preferences that you can set, such as what to do when the design environment is started (in the Startup category) and what happens when you add files to the project (in the Document > Files category). Take some time to look through the categories and familiarize yourself with the different options that are available.

Remember that you can click Help or press F1 to get more information about any of the settings in a specific category.

Planning Your Installation

The first step in creating a successful software installation is to plan it out.

In fact, planning your installation is one of the most important steps in designing a professional installer. Knowing what your installer needs to accomplish in advance will give you a clear goal to aim for and a solid plan to follow.

Tip: As with most things, the more planning you do now, the less repairing you'll have to do later. Investing some time in planning at the start can save you a lot of time in the long run.

There are several things you need to know in order to create an installer:

  • What files do you need to distribute?

  • Where do your files need to be installed?

  • What system changes need to be made?

  • What information do you need from the user?

This section will provide you with the information you need to answer these questions as quickly and accurately as possible.

What Files Do You Need to Distribute?

The first step in preparing your installation is to determine exactly what files your software requires for proper operation.

There are four basic types of files that you may need to distribute: program files, configuration files, operating system components, and shared application resources.

Program Files

Program files are the main files of your application. These files are essential to your application and are only useful in the context of your application. They can be executables, help files, documents, templates, or any other data files that your application requires. Program files usually make up the bulk of your software.

Configuration Files

Configuration files are used to store startup options, user settings, and other configuration options for your software. Information can be read from and written to these files during the normal operation of your application. These files are often referred to as config files, and come in many different formats, from traditional INI files (which adopt the same internal structure as Windows .ini files) to modern XML files.

Operating System Components

These files are usually included with the Windows operating system, but you may want to distribute the newest versions of certain files, or you may have developed custom system files of your own. These files are generally DLLs, OCX components, or hardware drivers like SYS files and VxDs.

Shared Application Resources

These are files that may be shared by more than one application, such as ActiveX controls, OCX components, and DLL files.

Some of the files that you need to distribute will be obvious, such as the main executable and help files. Others may be less apparent, such as DLLs and ActiveX controls installed in the Windows directories of your development system.

Note: Many of todays development tools require that you distribute runtime support files along with your application. Please consult your development tools documentation to determine what files you need to distribute with your software.

Often an executable in your application absolutely requires other files in order to work properly. These absolutely required files are known as dependency files.

Dependency Files

Dependency files are external support files that an executable requires for proper operation. In other words, they are external files that a program file depends on in order to function properly. Dependency files may include INI files, DLLs, ActiveX controls, OCX components, or any other support file type. Although its generally preferable to install dependency files in the same folder as the program that needs them, they are often installed in other locations, such as the Windows system directories.

Tip: Setup Factory has a built-in dependency scanner that you can use to identify dependency files and add them to your project. You can access this feature by choosing Tools > Scan File Dependencies.

Preparing the Directory Structure

The ultimate goal of a good installer is to get your software onto the users system in an easy and accurate manner. Although Setup Factory ensures both you and your users ease of use, the accuracy of the installation itself is largely up to you. Whether your files are installed in a structure in which they can function properly depends largely on where you tell Setup Factory to install those files.

The best way to ensure an accurate installation is to prepare the software in its finished state on your development system before you begin creating the installer. This means setting up the entire directory structure and all of the file locations exactly as you want them to appear on the users system.

The end result should be that your software is fully installed on your development system exactly as you want it installed on the users system.

Not only does this make it easy to test your software in its intended directory structure, but it also makes the process of designing the installer much quicker and easier for you. All you'll have to do is drag your application folder onto the Setup Factory project window, and the files and sub-folders will be recreated exactly the same on the users system. Below you'll find an example of a well-prepared directory structure.

Tip: You should fully test your software in its final structure before creating the installer.

Where Do Your Files Need To Be Installed?

Once you have your software organized, you need to determine exactly where each file needs to go on the users system. Although Setup Factory does a lot of this work for you by maintaining directory structures when you add files to your project, there are still some files that may need to be directed to different locations on the users system.

Here are some guidelines to help you determine where you should install your files on the users system. Once again, there are four basic types of files that you may need to distribute: program files, configuration files, operating system components, and shared application resources.

Installing Program Files

Program files should be installed in a folder that the user chooses during the installation process. Throughout this manual and in the Setup Factory program, this folder is referred to as the application folder. The path to the application folder is represented by the built-in session variable %AppFolder%.

Tip: For more information on session variables, see Chapter 5.

Its okay to install program files in sub-folders within the application folder-in fact, organizing your program files into sub-folders is a very good idea. Your files don't all have to be in the application folder itself; the folder that the user chooses can be used as a common application folder, with sub-folders for all of your program files.

If the users aren't given an opportunity to choose an installation folder, the path that you provided as the default value for %AppFolder% will be used. You can provide a default path for the application folder on the Session Variables tab of the Project Settings dialog. (To access this tab, choose Project > Session Variables from the menu.)

Installing Configuration Files

In the past, initialization or INI files were often installed in the Windows folder (%WindowsFolder%). This is definitely not necessary or even beneficial in all cases. Unless your application shares a configuration file with other programs, its best to install the file in the application folder along with your program files.

You should avoid installing any files in the Windows folder, or in any other folders where critical operating system files are stored, unless it is absolutely required by your application.

Installing Operating System Components

Operating system components, such as DLL or OCX files, are traditionally installed in the WINDOWS\SYSTEM folder (%SystemFolder%). If your application doesn't need to share these files with other applications, its best to install them in your application folder (%AppFolder%) instead.

Installing Shared Application Resources

Shared application resources, such as some ActiveX controls or DLL files, are generally installed in the WINDOWS\SYSTEM folder (%SystemFolder%).

Note: Many DLL and OCX files are COM servers, also known as OLE components and ActiveX controls. As such, they will need to be registered with the operating system before they will be available for use by your application.

Setup Factory will automatically try to detect files that require registration when you add them to your project. You can also manually indicate files that you want Setup Factory to register by using the options on the Advanced tab of the File Properties dialog. Or you can use an action like System.RegisterActiveX to register a file manually at run time.

Keep in mind that some DLL and OCX files have dependency files themselves, and these dependency files need to be distributed and possibly also registered before the DLL or OCX files can be used. You should consult the documentation for your components to determine what dependencies they have.

Note: Many OCX and DLL controls ship with a dependency file. The dependency file typically has the same filename as the control with a .DEP extension, e.g., Control.ocx would have a dependency file named Control.dep. These dependency files can be opened and viewed with a text editor (such as Notepad) and can tell you a lot about what, if any, dependencies the control may have.

Tip: You can also use Setup Factory's built-in dependency scanner to identify any dependency files your components may have. You can access the dependency scanner by choosing Tools > Scan File Dependencies.

What System Changes Need To Be Made?

The next step is to think about what changes, if any, need to be made to the users system. This can include changes to system files (such as WIN.INI, CONFIG.SYS, SYSTEM.INI and AUTOEXEC.BAT), changes to the Registry, and even such things as installing and registering fonts. All of these changes can be handled easily using Setup Factory actions.

For more information on actions, see Chapter 4.

What Information Do You Need from the User?

The final step in planning your software installation is to consider what information you will need from the user, and what information you will need from the users system. For example, in order to personalize your software or register it to a specific user, you may want to ask the user to provide their name on a User Information screen. Or, you may want to ask the user for a serial number on a Verify Serial Number screen.

For more information on screens, see Chapter 3.

Tip: You can also use actions to prompt the user for information (e.g. Dialog.Input) and to gather other information directly from the users system (e.g. System.GetUserInfo). See the program reference for a complete list of the actions available in Setup Factory.


Chapter 2: Working with Files

Working with Files

Installing the right files to the right places is the key to performing a successful installation. The files that make up your software need to get from your development system to the appropriate locations on the user's computer. Regardless of whether you're distributing files on CD-ROMs, DVDs, or in a single, downloadable setup executable, Setup Factory allows you to install all of your files with the utmost precision.

In fact, the installation of files is the main purpose of an installer. As such, you are expected to be completely familiar with files and folder structures in order to use Setup Factory. If you need more information on the basics of files and hierarchical folder structures, please consult Windows Basics.

Note: Files are your software—and you are responsible for getting those files onto the users' systems without causing any harm. A solid understanding of files and folders is critical to building a professional installer.

In This Chapter

In this chapter, you'll learn about:

• The project window

• The Archive and External file lists

• Filtering the file list

• Folder references

• Adding files and folder references

• Removing files and folder references

• File and folder reference properties

• What %AppFolder% is

• Working with multiple files

• Missing files

• Primer files

The Project Window

The project window takes up most of the main screen and contains a list of all the files that you have added to your project. From this list you can highlight specific files and view or edit their properties.

The file list tabs on the project window allow you to switch between the two separate file lists in Setup Factory: the Archive file list, and the External file list.

The Archive File List

The Archive file list (or "Archive tab") is for files that you want compressed and stored in the setup executable. In other words, this list is for files that will be included in your installer.

When Setup Factory builds the setup executable, it compresses all the files in the Archive file list and packs them right into the setup executable file. The part of the setup executable where the files are stored is known as the setup archive. The Archive file list is where you add the files that you want to store in the setup archive.

The External File List

The External file list (or "External tab") is for files that you don't want compressed and stored in the setup executable. In other words, this list is for files that will be distributed with your installer.

When Setup Factory builds the setup executable, it includes all the information it knows about the files on the External tab, such as where the files are expected to be at run time (the run-time source location), and where you want them to be installed to (the run-time destination folder). But it doesn't actually include the files in the setup executable. Instead, you're expected to make sure that those files will be where the installer expects them to be at run time. Usually this is done by distributing the files along with the setup executable on the same CD-ROM.

Note: In previous versions of Setup Factory, the External file list was known as the "CD-ROM tab."

File List Columns

Both file lists have columns that display different information about each file in your project. You can sort the information along any of the columns by clicking on the header for that column. If you click on the same header again, the files will be sorted by that category in reverse order.

You can customize the columns by choosing View > Columns. This opens the Columns dialog, where you can choose which columns to display in the list, and change the order (left to right) that the columns are listed in.

Tip: Moving a column up in the columns list moves it to the left in the file list; moving a column down in the columns list moves it to the right.

File List Items

The items that appear in the Setup Factory file lists refer to files on your system. When you add a file to your project, the file is not copied into the project. It is only referenced by the project.

In other words, only the path to the file (and a few other properties, such as the size of the file) is stored in your project. If the original file is renamed, moved or deleted, Setup Factory won't be able to build it into the setup executable. (In fact, it will show up in the file list as a missing file.)

The file itself, however, is not part of the project. If you copy your project from one system to another, you will not be able to build it unless you also copy the files, and place them in the exact same folder structure—in other words, you must place the files where the project expects them to be located.

Note: The files that your project references are commonly referred to as source files.

Filtering the File List

You can apply a filter to the file list so it only shows files that meet specific criteria. For example, you could filter the list to only show files that are larger than 5 MB, or files that will be installed to a specific location.

This is all done using the Filters toolbar.

Clicking the Edit filters button on the toolbar opens the filters manager, where you can configure the list of filters that appear in the drop-down selector on the toolbar.

The filters manager allows you to define custom filters using a wide range of criteria.

Creating a Filter

Setting up a new filter is incredibly easy. After clicking on Add in the filters manager, you simply give the filter a name:

…then select the property you want to filter on:

…select the rule that you want to use:

…and finally provide the criteria:

Once filters have been defined, you can easily switch between them using the drop-down selector. The filters are saved on a global basis, so they can be used in all of your projects.

Folder References

Folder references are similar to files, but they reference a folder on your system instead of a single file. They're useful for including folders full of files without having to reference each file individually.

For example, if you have a folder full of images that you need to install, you can use a folder reference to add the entire folder to your project. This also lets you configure the settings for all of those files from a single item in the file list.

You can even choose whether or not to reference folders recursively. In other words, you can choose whether or not to include the files in any subfolders (and subfolders of subfolders, and so on) that may be in the selected folder. (This is in fact the default behavior of folder references; however, you can choose to only include the files in the immediate folder if you want by simply turning off the "Recurse subfolders" option.)

Each folder reference also has a File Mask setting that you can use to include only files that match a specific pattern. For instance, if you wanted to use different settings for the .jpg files and the .bmp files in your product's Images folder, you could use two folder references—one for each type. So, for example, you could set up one folder reference to add everything beneath C:\Program Files\GiddyApp\Images that matches "*.jpg" and another one to add everything in that same path that matches "*.bmp." You could then configure their settings differently—for example, you could turn off compression for the .jpg files so Setup Factory won't try to compress them when you build the project, which could shorten the build process if you have a lot of image files.

Note: During the build process Setup Factory performs a test compression on each file, and automatically turns compression off for any file that isn't reduced in size after it's compressed. JPEG files are already compressed, so normally Setup Factory ends up turning compression off for them anyway.

Tip: Folder references are one of the most powerful features in Setup Factory! Be sure to use them to your advantage.

Overriding Individual Files

There may be cases where you want to include a folder full of files, but you want to use different settings for some of the files in the folder. Setup Factory makes this incredibly easy to accomplish because you can override a folder reference with individual file items.

The rule is simple: the settings for individual file items always take precedence over folder references. So if you have a folder reference that happens to include files A, B, and C, and you also add file B to your project on its own, the settings for the standalone file item will be used for file B, and not the settings for the folder reference.

Note: It doesn't matter what order the files are in…individual file items always override folder references.

Before Adding Files

Before you start adding files to your project, make sure you have all of your files properly installed on your system. Your local directory structure affects the destination paths that Setup Factory assigns to files as they are added to your project, so it's important to have your application's directory structure laid out on your system the same way you want it to end up on the user's.

Adding Files

There are two ways to add files to your Setup Factory project: you can add files from within Setup Factory, or you can drag and drop files onto the project window.

Adding Files from Within Setup Factory

To add files from within Setup Factory:

1. Click on the Archive tab or the External tab.

Use the Archive file list if you want the files to be included in the setup executable, or the External file list if the files will be distributed separately.

2. Choose Project > Add Files from the menu.

This will open the Add Files to Project dialog.

Tip: You can also click the Add Files button on the toolbar, press the Insert key, or right-click on the project window and select Add Files from the right-click menu.

3. Select the add mode that you want to use.

The "Selected files only" option will only add the files that you select.

The "All files in this folder" option will add all of the files in the folder that the Add Files to Project dialog is currently displaying.

The "All files in this folder and all sub-folders" option will add all of the files in the current folder, and all of the files in any sub-folders as well.

4. Select the files that you want to add, or navigate to the folder where all the files (and possibly sub-folders) that you want to add are located.

Depending on the add mode you chose, you either need to select one or more individual files in the browse dialog, or navigate into the folder that you want to add files from.

5. Click the Add button to add the files to your project.

Once you click the Add button, the files will appear in the file list.

Dragging Files onto the Project Window

To add files by dragging and dropping them:

1. Open the folder where your files are located.

The "C:\Program Files\Widget Master Pro" folder in Windows:

2. Select the files that you want to add to your project.

You can hold the Ctrl key down while clicking on files to select more than one file at a time.

3. With your files still selected, hold the left mouse button down and drag the files over the Setup Factory project window.

This is just like dragging icons around on the desktop.

4. Let go of the mouse button to "drop" the files onto the project window.

Once you drop the files onto the project window, they will appear in the file list.

Adding Folder References

There are two ways to add folder references to your Setup Factory project: you can add them from within Setup Factory, or you can drag and drop folders onto the project window.

Adding Folder References from Within Setup Factory

1. Click on the Archive tab or the External tab.

Use the Archive file list if you want the folders to be included in the setup executable, or the External file list if the folders will be distributed separately.

2. Choose Project > Add Folder Reference from the menu.

This will open the Browse For Folder dialog.

Tip: You can also click the Add Folder Reference button on the toolbar, press Ctrl+Insert, or right-click on the project window and select Add Folder Reference from the right-click menu.

3. Select the folder that you want to add.

Simply browse for the folder that you want to add. When you select a folder, its name will appear in the Folder field near the bottom of the dialog.

4. Click OK to add the folder to your project.

When you click the OK button, the folder reference will appear in the file list.

Dragging Folders onto the Project Window

To add a folder reference by dragging and dropping a folder:

1. Open the containing folder where your folder is located.

2. Select the folder that you want to add to your project.

In other words, click once on the folder that you want to add. (But don't navigate into the folder, or you won't be able to drag it.)

3. With your folder still selected, hold the left mouse button down and drag the folder over the Setup Factory project window.

This is just like dragging icons around on the desktop.

4. Let go of the mouse button to "drop" the folder onto the project window.

Once you drop the files onto the project window, the drag and drop assistant will appear, asking if you want to add the folder as a folder reference.

5. Click Yes to add the folder as a folder reference.

Clicking Yes on the drag and drop assistant will add the folder to your file list as a folder reference.

Note: Clicking No will add all of the files inside the folder as individual file items instead.

Removing Files

To remove files from your Setup Factory project:

1. Select the files that you want to remove on the project window.

Simply click on the file items that you want to remove.

2. Choose Project > Remove Selected.

Choosing Project > Remove Selected from the program menu will remove the selected file items.

Tip: You can also click the Remove Files button, press the Delete key, or right-click on the project window and select Remove from the context menu.

Note: Removing files from your project removes the file items from the file list, but does not delete the original files. The original files remain completely unaffected.

Removing Folder References

Removing folder references is exactly like removing files. Simply select the folder references that you want to remove and choose Project > Remove Selected (or press the Delete key, etc.).

File Properties

You can use the File Properties dialog to view and edit the settings for any file in your project.

To access the File Properties dialog:

1. Select a file on the project window.

Simply select the file item that you want to edit.

2. Choose Project > File Properties.

This will open the File Properties dialog, where you can view and edit the properties of the file you selected.

Tip: There are several other ways to access the file properties as well. You can click the File Properties button, press Ctrl+Enter, right-click on the file item and select File Properties from the right-click menu, or simply double-click on a file in the list.

There are six tabs on the File Properties dialog: General, Shortcuts, Advanced, Conditions, Packages, and Notes.

General

The General tab is where you will find information about the file itself, such as its name and location on your system. This is also where you can view or edit the destination path, and the overwrite settings for the file.

Source Folders

Since a Setup Factory project only contains references to files, each file has a property that specifies where the file is located. This location is known as the source folder.

There are two kinds of source folders: local folders, and run-time folders.

Local Folders

Local folders are folders that are located within local access of your system or LAN. These specify the current location of the file on your system.

Setup Factory uses the local folder to retrieve the file's information (e.g. when you open a project) and to locate the file when it builds the setup executable (i.e. when you build the project).

Run-time Folders

Files in the External file list have an additional property known as the "run-time folder." The run-time folder specifies the run-time location where the file will be when the user runs your setup file. In other words, it represents the location of an external file at the time of the installation.

Note: The run-time source path only applies to files on the External tab. The files on the Archive tab are always located in the setup executable archive at run time.

Destination Paths

Destination paths specify where the files are intended to end up on the user's system. Though this seems simple enough, it is complicated by the fact that you can't predict the layout of the folder structure on the user's system. For instance, if you want to install a file in the user's "My Documents" folder, how do you know what the full path to that folder is? It could be anything from "C:\Documents and Settings\JoeUser\My Documents" to "F:\Joe’s Docs."

Setup Factory gets around this uncertainty by providing you with a number of built-in session variables for common system folders. These are essentially placeholders (like %MyDocumentsFolder%) that you can use in your file paths, and that will be replaced by the corresponding path on the user's system at run time. You simply use the appropriate placeholder, and Setup Factory will take care of investigating what the actual path is when your user runs the setup file.

For more information on session variables, see Chapter 5.

%AppFolder%

Most installations involve asking the user to confirm where they would like the software installed. In order to accommodate the user's choice in this matter, Setup Factory uses a session variable to represent the main folder that your software will be installed in. The name of this session variable is %AppFolder%, which is short for Application Folder, i.e. the folder where your software application is to be installed.

Tip: You can set a default path for %AppFolder% by choosing Project > Session Variables, and you can allow the user to change it (i.e. select a different path) by including a Select Install Folder screen in your project.

Automatic Destination Folder Prediction

When files are added to a Setup Factory project, Setup Factory tries to set a "best guess" value for the destination folder of each file. It does this in two ways.

The first time you add any files to the Archive file list, Setup Factory assumes that you are adding files from the "main" folder where your application is installed on your system. It sets these files to be installed in %AppFolder%, or in sub-folders of %AppFolder% if the files were in subfolders of the main folder—in other words, it preserves the relative folder structure of the files that you add.

Once you already have files in the file list, Setup Factory goes even further when you add new files to the project. First, it compares the path of each file that you're adding to the local source path of each file in your project. If it finds another file in your project that was from the same source folder on your system, it uses that file's destination path to guess what the new file's destination path should be. (Normally, files that are located in the same place on your system will be installed to the same place on the user's system.)

In other words, Setup Factory tries to base each new file's destination path on the destination path of a file in your project that is in the same location on your system.

If there are no files in your system from the same source location, the new file is configured to simply use %AppFolder% as the destination folder path.

Shortcuts

The Shortcuts tab is where you can configure the shortcut options for the selected file. You can use this tab to have Setup Factory automatically create a shortcut icon for the file in the user's Start menu or on the user's desktop at run time.

Creating Nested Shortcuts

A nested shortcut is a shortcut file that is located in a sub-folder of a shortcut folder. In other words, it's a shortcut in a folder that is located or "nested" in another folder.

You can easily create nested shortcuts with Setup Factory by specifying a custom shortcut path. Simply include the nested folders in the path that you provide in the Custom field on the Shortcuts tab.

In other words, just enter the full path to where you want the shortcut file to end up, and if any of the folders in the path don't exist, Setup Factory will automatically create them for you.

Advanced

The Advanced tab is where you can configure advanced options for the selected file. This is where you can override certain default installation settings, such as whether the file will be compressed before storing it in the setup executable, whether it will be uninstalled automatically by your installer's uninstall routine, and what attributes will be assigned to the file after it's installed. You can also specify whether the file should be registered as a TrueType font, or even whether it should be registered as a shared OLE or ActiveX component using DLLRegisterServer.

Registering Files

There are two ways that you can register files (such as ActiveX controls) in Setup Factory. The easiest way is to simply select the "Register COM interfaces" check box on the Advanced tab of the File Properties dialog for the file you want to register.

The alternative method is to use a System.RegisterActiveX action to register a file after it has been installed.

For more information on the Register COM interfaces option and the System.RegisterActiveX action, please consult the program reference.

Registering Fonts

There are two ways that you can register TrueType fonts in Setup Factory. The easiest way is to select the "Register as TrueType font" check box on the Advanced tab of the File Properties dialog for the file you want to register. The file must be a valid Windows TrueType font (.ttf) file.

The alternative method is to use a System.RegisterFont action to register a .ttf file after it has been installed.

For more information on the Register as TrueType font option and the System.RegisterFont action, please consult the program reference.

Conditions

The Conditions tab is where you can edit settings that affect whether the file will be included in the setup executable, and whether it will be installed. In other words, it is used to conditionally include or exclude a file from the setup at build time or run time.

The list of build configurations allows you to select the build configurations that the file will be included in. The file will only be included in the setup executable if it is included in the build configuration that is in effect when you build the project.

The list of operating systems allows you to specify which operating systems the file will be installed on. The file will only be installed on an operating system if it is marked with a check in this list. So, for example, if you uncheck Windows XP for a file, it will not be installed on Windows XP.

The script condition is a short expression written in Lua script for the file. It must evaluate to a Boolean value of either true or false. At run time this result will determine whether or not the file will be installed.

Packages

The Packages tab is where you can select the packages that you want the selected file to belong to. The Packages tab lists all of the packages that have been configured in your project. You can add the currently selected file to one or more packages by clicking on the check boxes in this list.

The file will be assigned to the packages that have check marks beside them.

For more information on packages, see Chapter 6.

Notes

The Notes tab is where you can type any notes that you want to keep about the file. These are not used by the installer, and are not included in the setup executable at all. The Notes tab is simply a convenient place for you to keep notes about the file for your own purposes. For example, you could list any special instructions involved in preparing the file for the build process, or you could keep track of who last edited the file's properties.

Folder Reference Properties

For the most part, Folder References have almost exactly the same properties as files do. In fact, the Conditions, Packages and Notes tabs are exactly the same. Here are some differences worth mentioning:

• On the General tab, folder references have a File Mask setting that allows you to include or exclude a range of files that match a filename pattern, e.g. "*.exe"

• On the General tab, folder references have a "Recurse subfolders" option that controls whether files in subfolders (and their subfolders) should be included as well.

• There is no Shortcuts tab for folder references.

• On the Advanced tab, some of the OLE/ActiveX and Font options do not exist because they cannot be applied to multiple files.

Working with Multiple Files

You can use the Multiple File Properties dialog to edit the properties of more than one file (or folder reference) in your project at a time.

To access the Multiple File Properties dialog:

1. Select more than one file on the project window. (You can select multiple files by pressing and holding the Ctrl key or the Shift key while you click on the files.)

2. Choose Project > File Properties from the menu.

(You can also click the File Properties button, press the Ctrl+Enter key, or right-click on the files and select File Properties from the right-click menu.)

This will open the Multiple File Properties dialog, where you can view and edit the properties of the files you selected.

The Multiple File Properties dialog is similar to the File Properties dialog, but there are some important differences:

• There is no Notes tab.

• You cannot enter text in a field directly; instead, you must click on the Edit button to the right of the field, and use the Edit Multiple Values dialog to change the text. Note that the Edit Multiple Values dialog allows you to completely replace the text for all selected files, append (or prepend) some text to the value for each selected file, or search and replace among the values for all selected files.

• Check boxes on the Multiple File Properties dialog have three states:
enabled ( [image] ), disabled ( [image] ), and mixed ( [image] ). The mixed state preserves the settings for that check box in all of the selected files.

• The Overwrite setting includes an option in the drop-down list to use the original values for each selected file.

For more information on using the Multiple File Properties dialog, please consult the program reference.

Missing Files

Since Setup Factory only records an informational link to each file, and doesn't actually maintain a copy of the file itself, it's possible for files to go "missing" from Setup Factory's point of view. For example, if a file in your project is moved to another folder, Setup Factory will no longer be able to find it at its original location. The same thing happens when a file is renamed or deleted. Setup Factory only knows to look for a file at the place where it was when you "showed" the file to Setup Factory by adding it to your project.

Although Setup Factory might not know where a missing file has ended up, it definitely knows when a file is missing. Whenever a file in your project can't be found at its original location, Setup Factory displays the file's information on the project window in red instead of black. The red color makes it easy for you to see which files in your project are missing.

The file's status will also show as "Missing" instead of "OK" in the Status column on the list view.

Tip: A quick way to determine which files are missing in your project is to click on the Status column header to sort the files in the list view according to their status.

If you find that your files are suddenly playing hide-and-seek with Setup Factory, try to remember if you've made any changes to your files recently. If you moved the files, you can try moving them back. If you renamed the files, you can restore the original names. If you deleted the files, you'll have to replace them.

If Setup Factory still shows the files in red after you've corrected the situation, you probably just need to refresh the display. To do so, simply choose View > Refresh from the menu, or press the F5 key. Refreshing the display causes Setup Factory to re-examine the location of every file in your project.

Note: Setup Factory automatically refreshes the display for you when you open a project or initiate the build process.

If you moved, renamed, or deleted the files on purpose, and you want Setup Factory to use the files at their new locations, remember the files by their new names, or just forget about the past and move on, you'll need to change the local source path on the File Properties dialog for each file. This can easily be done by selecting all the files and then modifying their properties using the Multiple File Properties dialog.

Primer Files

Primer files are just regular files that get extracted from the setup executable before the installation process begins. This means you can use primer files at the very start of the installation process, right after the user runs the setup executable.

You can make any file a primer file simply by adding it to the Primer Files tab on the Resources dialog. The files on this tab will be included in the setup executable when you build the installer.

Primer files are automatically extracted to a temporary folder at run time. The path to this folder is automatically stored in a session variable named %TempLaunchFolder%. You should use this session variable in actions when you need to access your primer files.

Primer files make it easy to run a program on the user's system before the rest of your files are installed. Just add the program to the list of primer files, and execute it with a File.Run action early in the installation process.

For example, you might need to execute a custom program or DLL function before your software is installed—perhaps to perform some product-specific, low-level pre-installation tests on the user's hardware, and write the results to the Registry. By adding your custom program or .dll to the list of primer files, you could distribute it "inside" your setup executable and still be able to run it before any of the "normal" files in your project are installed.

Tip: Another way to access files at the start of the installation process is to distribute them "alongside" your installer. For instance, you could store the files "externally" on the same CD-ROM, and access them directly; or, you could download the files from your web site using an HTTP.Download action in the On Startup project event.


Chapter 3: Creating the User Interface

Creating the User Interface

Creating the user interface (or UI) is one of the most important aspects of any setup since the UI is the first thing your end users will see when they run your installer. Making a great first impression with a good-looking UI is something that all users of Setup Factory should be concerned about.

This chapter will introduce you to the user interface and get you well on your way to creating a sharp and consistent look and feel for all of your projects.

In This Chapter

In this chapter, you'll learn about:

  • The user interface

  • The background window

  • Screens

  • Themes

  • Taskbar settings

  • Dialog and Status Dialog actions

The User Interface

You can think of the user interface (UI) as any part of the setup that the end user will see. When a screen is displayed, the end user is seeing part of the user interface. When the end user clicks the Next button, the end user is interacting with the user interface.

The basic elements of the user interface are:

  • The Background Window

  • Screens

  • Themes

  • Taskbar visibility

  • Any actions that generate a UI element (e.g. Dialog.Message, StatusDlg.Show)

The Background Window

The background window is a maximized window that will appear behind all screens in your installation. Its main use is to focus the end users attention on your setup by blocking out the rest of the desktop.

The settings for the background window can be found in the menu under Project > Background Window. The next few sections will explain all the settings available for the background window.

Window Style

The window style options control the title bar and border styles that will be applied to the background window. All background windows will be full screen and will cover the task bar regardless of the style you choose.

There are three different window styles:

  • Standard

  • Bordered

  • Kiosk

Standard

The standard window style will display a background window with the features of a normal window (i.e., a title bar with a close button and a standard window border).

You should probably choose the standard window style if you want to present your setup and background window as a standard application. The full background window allows you to display extra information, but the border makes it known to the end user that this is just a standard application.

The standard window style also lets the end user move the background window by dragging the window via the title bar.

Note: The text on the window title bar is controlled by the %WindowTitle% session variable.

Bordered

The bordered window style has the same border as the standard window style but does not have a title bar.

The bordered style is a good choice if you do not want the end user to be able to move your background window, but you still want them to know that your installation is just another application (made clear by the border).

Kiosk

The kiosk window style will create a background window without a title bar or border.

This is an effective style to choose if you want an unmovable background window that thoroughly engages the end users attention. Because there is no border or title bar to differentiate your installation from the rest of the operating system, there is nothing to compete with your background window.

Window Appearance

The window appearance settings control the appearance of the background window. These options control what the interior of the background window will look like. You can think of the interior of the background window as everything but the title bar and the border.

There are three appearance options: solid color, gradient, and image.

Solid Color

The solid color option will color the interior of the background window a single color.

Gradient

The gradient option will create a vertical gradient on the interior of the background window. The left color picker selects the color for the top of the background window and the right color picker selects the bottom color.

Image

The image option will use the image that you select to fill the interior of the background window.

The image you select will be stretched to fill the interior of the background window regardless of its size. This means that your image will vary in appearance on computers with different screen resolutions. It is very important to select an image that will look good at different sizes.

Background Window Text

The background window text settings control the look and position of the text that can be displayed on the interior of the background window.

Three separate text elements can be displayed on the background window: a heading, a subheading, and a footer. Each of these has similar formatting options, including the font type, the color of the text, whether to draw the text in a 3D style, the 3D color (if enabled), and the alignment of the text.

Heading

The heading text will be displayed at the top of the interior of the background window. It is usually used to display important information such as the name of your product or your computer name.

Subheading

The subheading text will appear directly below the heading text and can contain your products version number, a marketing message, or any other message.

Footer

The footer text will appear at the bottom of the interior of the background window and is useful for displaying copyright information or website addresses.

Screens

The most important aspects of your user interface are the screens that you choose to display, since this is where your end user will actually interact with the setup. Screens allow you to provide important information (such as your license agreement) and allow your user to make decisions (such as where to install your product).

Screens are the individual windows that make up your installation. When you navigate through an installation by clicking the Next and Back buttons, you are navigating from screen to screen.

Tip: You can think of the screens in your project as steps in a wizard, walking your user through the process of installing your software.

In general, each screen performs a single task, like showing a welcome message, allowing the end user to select which packages they want to install, or letting the end user select the name of a shortcut folder. If you want to perform a major setup task, chances are you will need a screen to do so.

The Screen Manager

The screen manager is where you will configure all of your screens. There are two screen managers in Setup Factory: one for the installer (Project > Screens) and one for the uninstaller (Uninstall > Screens).

Aside from when the screens will be displayed, the only difference between the two screen managers is that the uninstallers screen manager does not allow you to configure the project theme.

Note: The project theme chosen in the installation screen manager affects your entire project and will be applied to screens in both the installer and uninstaller.

Screen Stages

There are six stages at which screens can be displayed in Setup Factory. The first three stages are related to the installation, and the last three are related to the uninstallation.

The three installation stages at which screens can be displayed are:

  • Before Installing

  • While Installing

  • After Installing

The three uninstallation stages at which screens can be displayed are:

  • Before Uninstalling

  • While Uninstalling

  • After Uninstalling

Each screen stage is represented by a tab on the appropriate screen manager.

You will notice that the installation and uninstallation stages are very similar. In fact, the only difference between them is when they occur, i.e. during the installation or during the uninstallation.

Once you understand how the installation stages work, you can apply the same knowledge to the uninstallation stages. That being the case, the following section describes the installation stages only; however, the information is easily applicable to the uninstallation stages by substituting the word uninstall wherever you read install.

Before Installing

The Before Installing screens are displayed before the actual installation of any files occurs. In general, if the end user cancels the setup during this stage, no files will be installed on their computer.

This stage is used to perform such tasks as displaying your license agreement and allowing the end user to select where your product will be installed.

While Installing

The While Installing stage occurs while the files are being installed onto the end users computer. This stage differs from both the Before Installing and After Installing stages in that only one screen can be displayed (as opposed to a sequence of screens), and it must be a progress screen.

This stage is used to display the file installation progress as it occurs. In other words, while your files are being installed onto the end users computer, the screen you chose for the While Installing stage will display information about the progress of that installation, such as what file is being installed, what percentage of all files has been installed so far, and what percentage of the current file has been installed.

After Installing

The After Installing stage is the final screen stage and occurs after all of the files have been installed onto the end users computer.

This stage is typically used to show a reboot advisement (if needed), provide any post-installation instructions, and inform the user that the installation has finished successfully.

Adding Screens

Adding a screen to your setup is as easy-you just click the Add button at the bottom of the screen manager.

Note: The While Installing screen stage is different since a maximum of one screen is allowed. For this stage, the button is labeled Change instead of Add.

Clicking the Add button brings up a screen gallery where you can select from a variety of screen types. Once you've selected the type of screen you want, simply click the OK button to add it to the list of screens for the stage that you're currently working on.

Removing Screens

To remove a screen from your installation, simply select it in the screen list and click the Remove button.

Tip: If you remove a screen from your installation by accident, you can undo the deletion by pressing CTRL + Z.

Ordering Screens

In general, the order in which screens appear in the screen manager will be the order in which they appear during that screen stage. The screen that is at the top of the list will appear first and the screen that is at the bottom of the list will be the final screen of that stage.

To change the order of your screens, simply select a screen in the list and click the Up or Down button until its in the desired location. Or, if you prefer, you can simply drag the screen from one position to another.

Tip: You can also use the cursor keys to move a screen up or down in the list. Simply select the screen you want to move, and press Alt+Up or Alt+Down.

Editing Screens

To edit a screens properties, just select it in the list and click the Edit button.

Clicking the Edit button opens the Screen Properties dialog where you can edit and customize all of the settings for that screen.

Tip: You can also edit a screen by double-clicking on it in the list.

Screen Properties

The Screen Properties dialog is where you can edit the properties of a specific screen. All Screen Properties dialogs have the same four tabs (although the specific content on these tabs may differ): Settings, Attributes, Style and Actions.

Settings

The Settings tab allows you to edit properties that are specific to the selected screen. Each screen type has different settings that are specific to that type of screen.

For example, a Check Boxes screen will have settings that apply to check boxes on its Settings tab.

For more information on the specific screen settings, please see the program reference.

Attributes

The Attributes tab contains settings that are common to all screens. The only differences that you will find between Attributes tabs are that progress screens lack options for the Next, Back, and Help buttons. (Those buttons don't exist on progress screens.)

The Attributes tab is where you can configure which banner style to use, the name of the screen, and the navigation button settings.

Style

The Style tab is where you can override the project theme on a per-screen basis. By default the project theme is applied to all screens throughout your project, however there might be some instances where you feel a certain screen needs something a bit different in order to stand out. You can use the Style tab to override any of the theme settings on a specific screen. (The changes will only be applied to that screen.)

Actions

The Actions tab is where you can edit the actions associated with the screens events.

For more information on actions and events, please see the help file and Chapter 4.

The Language Selector

The Settings and Attributes tabs both have a language selector in the bottom right corner. The language selector is a drop-down list containing all of the languages that are currently enabled in the project. It is used for creating multilingual installations.

Selecting a language in the list allows you to edit the text that will be used on the screen when that language is detected.

Note: Unlike previous versions of Setup Factory, the language selector allows you to display different text on a screen for specific languages without having to create a separate screen for each language.

Session Variables

Session variables play a large part in the way that screens work and how they display their text. Anytime you see something in Setup Factory that looks like %ProductName%, what you are looking at is a session variable.

Note: A session variable is essentially just a name (with no spaces) that begins and ends with %.

Session variables are very similar to normal variables in that they serve as containers for values that may change. We say that values are assigned to or stored in session variables. When you use a session variable, its name (i.e. %ProductName%) is replaced at run time by its value (i.e. Setup Factory). Session variables are basically placeholders for text that gets inserted later.

Session variables are often used in the default text for screens. They are automatically expanded the first time the screen is displayed, so instead of seeing %ProductName% on the screen, the end user will actually see the name of your product that you entered in the session variable editor: Project > Session variables.

Session variables are also used to store return values when screens or controls need them. For example, the Select Install Folder screen stores the installation folder path in a session variable named %AppFolder% by default.

Tip: Session variables can be created and changed at run time using actions like SessionVar.Expand, SessionVar.Get, SessionVar.Remove, and SessionVar.Set.

For more information please see Chapter 5, which discusses session variables in more detail.

Screen Navigation

Screen navigation can be thought of as the path that the end user takes through your installation. The end user navigates forward through various screens by clicking the Next button, and backward through the screens by clicking the Back button.

Screen navigation is basically a linear path from the top of your screen list in the screen manager to the bottom. Generally, the order of your screen list in the screen manager is exactly the order in which the navigation will proceed.

Although there are other ways to control the path through the screens (e.g. using actions to create a branching path), in most cases the default behavior is all that is needed.

How Screen Navigation Works

In its simplest form, screen navigation is when the end user moves forward or backward through your installation by clicking the Next and Back buttons. By default, this moves the end user down or up through the list of screens on the screen manager.

This is actually accomplished using actions. Each screen has Screen.Next and Screen.Back actions on its On Next and On Back events which are performed when the Next and Back buttons are clicked. If you ever need to, you can modify or override the default behavior of any screen by editing or replacing the default actions. Most of the time, however, you will not even need to know that the actions are there.

Navigation Buttons

Navigation buttons are the Back, Next, and Cancel buttons that are usually visible along the bottom (or footer) of each screen. The Next button moves the end user down the screen list from the top to the bottom, the Back button moves the end user up through the screen list, and the Cancel button stops the users navigation by canceling the installation.

The settings for these buttons can be found on the Attributes tab of the screen properties dialog for each screen. There you can change the text, enabled state and visible state of these buttons.

The two options for the visibility state are self-explanatory; they make the button either visible or invisible. The two options for the enabled state make the button enabled or disabled. If a button is in the enabled state, it looks and functions like a normal button; it will depress when the user clicks on it, and the text is displayed in its normal color (usually black). When a button is in the disabled state, however, it will not respond to the users mouse, and is typically drawn in less prominent gray colors (also known as being ghosted or grayed out).

Each navigation button has an event that will be fired when the button is clicked. These events can be found on the Actions tab of the screen properties dialog.

Note: A Help button is also available on the footer of each screen but is generally not considered a navigation button.

Navigation Events

An event is something that can happen during the installation. When an event is triggered (or fired), any actions that are associated with that event are performed. Note that an event must be triggered in order for its actions to be performed-if an event is not triggered, the actions associated with it will not be performed.

Each event represents something that can happen while your installation is running. For example, all screens have an On Preload event, which is triggered just before the screen is displayed. To make something happen before a screen is displayed, you simply add an action to its On Preload event.

All of the three navigation buttons have an event that will be fired when they are clicked. The events are On Back for the Back button, On Next for the Next button and On Cancel for the Cancel button.

In the case of the three navigation buttons, navigation actions are executed when their respective events are fired. This allows the end user to navigate through the installation from the beginning to the end.

There are other events that are associated with screens but aren't necessarily related to screen navigation:

  • On Preload just before the screen is displayed.

  • On Help when the help button is selected.

  • On Ctrl Message triggered by a control on the screen.

Navigation Actions

There are six navigation actions available to you in Setup Factory: Screen.Back, Screen.End, Screen.Jump, Screen.Next, Screen.Previous, and Application.Exit. The most common of the six actions are Screen.Next and Screen.Back.

When the Next button is clicked, the end user is attempting to navigate from the current screen to the next screen or phase of the installation. The easiest way to implement this behavior is to insert the Screen.Next action on the On Next event. This is done by default for all screens.

The same holds true for the Back button; when the Back button is clicked, the end user is attempting to move backwards in the installation to the previous screen. To implement this behavior, a Screen.Back action needs to be executed when the On Back event is fired.

Note: The Screen.Back action moves backward in the installations history in the same way that a Back button does in a web browser. To move up (back) one screen in the screen list, use the Screen.Previous action.

In certain situations, simply moving down the screen list is not the appropriate behavior; instead, jumping to a specific screen in the screen stage is necessary. You can accomplish this by using a Screen.Jump action. If the goal is to jump to the next phase in the installation- i.e., to end the current screen stage a Screen.End action can be used to jump past all of the screens in the current screen stage.

To interrupt screen navigation, which usually occurs when the Cancel button is clicked, you can use an Application.Exit action. The Application.Exit action causes your installation to stop as soon as it is performed.

Note: For more information on the specifics of screen actions, please see the program reference.

Screen Layout

In Setup Factory choosing a layout for your screens and the controls is simple. You can switch between all three banner styles (top, side, and none) on any screen that you like, and the controls on your screens will dynamically position themselves ensuring that all of your information is visible.

Note: A control can be thought of as the visible elements on a screen, from edit fields, to radio buttons, to static text controls. However, when the term control is used, it does not generally refer to the navigation buttons or banner text.

Header, Body, Footer

Screens in Setup Factory are divided into three basic parts: the header, the body and the footer.

The header runs across the top of each screen and can be thought of as the area that the top banner fills.

The footer is similar to the header area except that it runs along the bottom of each screen. This is the area of the screen where the navigation buttons are placed.

Now that you know what the header and the footer are, you can think of the body as the rest of the screen. The body of a screen takes up the majority of each screen and will contain most of the screens information.

Banner Style

In Setup Factory the term banner refers to an area of the screen that is special and somewhat separate from the rest of the screen. You can use the banner area to display some descriptive text, an image, or both.

There are three different types of banner styles available in Setup Factory: none, top, and side.

The none banner style is the easiest of all three styles to understand since it means that there will be no banner displayed on the screen as seen below.

The top banner style will give you a long thin banner across the top of your screen (the header). This is the style that you will probably apply to the majority of the screens in your project. The top banner style supports two lines of text referred to as the heading text and the subheading text. This text is usually used to describe the current screen and/or provide some information about what is required of the end user.

The top banner style also supports an image that will be placed on the right hand side of the banner. Setup Factory will resize this image proportionally so that its height matches the height of the top banner. The width of the image can be as wide as you want and can take up the entire banner if necessary.

Any area of the top banner that is not covered by an image will be painted with a color according to the project theme as seen below.

The side banner style will give you a thick banner that runs down the left side of your screen. The side banner will start at the top of the screen and then stop at the top of the footer of your screen. The side banner style supports an image that will automatically be stretched or resized by Setup Factory to fill the entire side banner area as seen below.

Dynamic Control Layout

One of the best features in Setup Factory is the dynamic control layout ability of screens. Setup Factory will dynamically reposition the controls on your screen so that the maximum amount of information stays visible.

Dynamic control layout means that controls will resize and layouts will adjust automatically as you type. You no longer have to manually place your controls and you wont find yourself locked into a pre-determined amount of space; dynamic control layout means that the layout will be automatically chosen based upon your chosen control settings.

The dynamic repositioning of controls takes place within an area called the control area. The control area of a screen occupies a sub-section of the body of a screen; its size is controlled by the global theme.

The best part of the dynamic control layout feature is that it works without any effort on your part. Simply fill your screens with all of the information and controls that you desire, and Setup Factory will re-position all the controls so that everything is visible and a visually appealing look is achieved.

This is not to say that you do not have any control over how controls will be displayed on your screen; in fact, its just the opposite. Many screens (Edit Fields, Checkboxes, etc.) allow you to add as many as 32 controls to your screen, which Setup Factory will dynamically position. You have the ability to choose how many columns you want the controls displayed in, whether they are distributed horizontally or vertically and, in the case of the Edit Fields screen, how many columns each control spans!

If this seems a bit confusing, don't worry about it. The best way to understand the dynamic control layout feature is to use it. Try playing around with the settings of the Check Boxes or Select Install folder screens and observe how Setup Factory positions your controls to achieve the best look possible.

Tip: You can also add a custom screen to your project. A custom screen allows you full control over the number, position and types of controls you include in your screen. It is available in the screen gallery. For more information on custom screens please refer to the program reference.

Themes

A theme is a group of settings and images that control the way your installation looks. You've probably encountered themes before when using other applications or even Windows. Themes do not change what is displayed; instead, they change how it is displayed.

Themes in Setup Factory control the general appearance of your screens and the controls they contain. Rather then controlling the position of screen controls or the banner style used, themes control the color and font of screens and controls. Themes are project-wide and affect all screens in the installation and uninstall unless intentionally overridden on the style tab of the screens properties.

Themes provide an easy way to change the look and feel of your screens and controls without having to go to each screen and update it every time you wish to apply a new visual style.

Below is a Select Shortcut Folder screen with the "CD-ROM" theme applied:

The same screen with a custom theme applied:

Choosing a Theme

You can choose a theme for your project on the theme tab of the installation screen manager, which you can access by choosing Project > Screens.

A list of the available themes will be found in the project theme drop down. Selecting a theme in this drop-down list will apply the theme to all screens in your installation and uninstallation.

For your convenience Setup Factory provides a handy preview of the theme on the theme tab so that you will know what the theme looks like before you choose it.

As introduced above, themes affect the appearance of screens and their controls. For example, choosing a theme that colors all static text controls purple will result in all static text controls being purple, and choosing a theme that colors static text controls black will result in all static text controls being colored black.

Creating a Custom Theme

Setup Factory allows you to create your own custom themes. This provides you with an easy way to share the same custom look and feel between multiple projects.

Here is a brief step-by-step guide to help you in the creation of a custom theme.

1) Start a new project and save a copy of a pre-existing theme.

Start a new project by choosing File > New Project from the menu, then open up the theme settings by choosing Project > Screens making sure that the theme tab is selected.

The first step in creating a custom theme is to select a theme from the project theme drop down that you will use to base your new theme upon. If you cannot find a suitable theme, your best choice will be the default theme.

Once you have selected the theme that will be the basis for your new theme, use the Save As button in order to save a copy of the current theme.

2) Edit your new theme in the Theme Properties dialog and then press Ok to save your changes.

Make sure that your new theme is selected and press the edit button to bring up the theme properties dialog. Here you will be able to edit all of the properties of your theme. Once you have made all of your changes, simply press the Ok button and the changes to your theme will automatically be saved.

Now you have a working theme that will be available to you in all your Setup Factory projects.

Note: If you are not happy with the changes made while editing your theme, simply click the Cancel button and your changes will not be saved.

Note: Saved themes will be stored in a Themes folder located in the all user profile of Application Data. For example: C:\Documents and Settings\All Users\Application Data\IndigoRose\Setup Factory\9.0\Themes.

Overriding Themes

As stated earlier, project themes affect every screen in your installation and uninstall. While in the vast majority of situations this is the desired effect, there may be a few instances where this is not exactly what you want. Fortunately, Setup Factory allows you to override any or all of the theme settings on any of your screens.

As mentioned in the Screen Properties section, each screen has a style tab associated with its screen properties dialog. If you look at the Style tab you will notice that it looks identical to the Style tab on the theme properties dialog except that it has a checkbox in the top left corner labeled override project theme.

Enabling the override project theme option will enable the theme settings area and allow you to change any or all of the theme settings without affecting any of the other screens in your project.

Note: If you decide that you want to go back to the project theme on a screen where you have overridden the project theme, there is no need to re-create the screen. Simply go to the Style tab and uncheck the override project theme checkbox.

Other Options

There are a few other options in Setup Factory that relate to the user interface of your installation. These options may not be as important as screens or themes but just might provide the elements necessary to perfect your projects look and feel.

Taskbar Settings

The taskbar is the bar that runs across the bottom of all modern Windows operating systems beginning with the START button on the left. When a program is running, its icon and name will generally appear in a button in the taskbar.

Setup Factory allows you to choose whether or not to show an icon in the task bar and to choose what that icon will be. Both of these settings can be found on the Advanced tab of the project settings: Project > Advanced Settings.

To hide the taskbar icon simply check the hide taskbar icon checkbox on the Advanced tab. To choose a custom icon simply check the use custom icon checkbox to turn on the custom icon setting and then click the browse button to locate the icon of your choice.

Note: If you configure your installation to be a silent install in the advanced settings then no taskbar entry will appear.

Actions

Some of the actions available to you in Setup Factory are capable of showing user interface elements. These actions can be divided up into two main categories: Dialog actions and Status Dialog actions.

Dialog actions are used to show pop up dialogs to the end user. Examples include the Dialog.Message action that lets you display a message in a dialog, and the Dialog.TimedMessage action that lets you show a dialog with a message for specific amount of time.

A typical message dialog:

Status dialogs are the other main user interface elements that are available to you through scripting. Status dialogs are mainly used to show progress or status during a lengthy event like an HTTP.Download action or a File.Find action.

A Status dialog:

Status dialogs are shown and configured using actions like StatusDlg.SetMessage, StatusDlg.ShowProgressMeter, and StatusDlg.Show.

Note: It is generally recommended that progress be shown in a more integrated manner using a progress screen, however there are situations where a status dialog may be more appropriate.

Note: For more information on the Dialog and StatusDlg actions, please see the program reference.


Chapter 4: Actions, Scripts and Plugins

Actions, Scripts and Plugins

Actions are one of the most important features in Setup Factory. They are what you use to accomplish the specific tasks that make your installation unique. Each action is a specific command that tells your installer to do something, such as retrieving a value from the Registry.

Actions also allow your installation to react to different situations in different ways. Does the user already have the evaluation version of your software installed? Is an Internet connection available? You can use actions to answer these types of questions and have your installer respond accordingly.

Scripts are essentially sequences of actions that work together to perform a specific task. Plugins allow you to extend the built-in actions with additional libraries of commands.

Together, actions, scripts and plugins allow you to extend the default functionality of a Setup Factory installation with virtually limitless possibilities.

In This Chapter

In this chapter, you'll learn about:

• Actions—what they are and what they’re good for

• The action editor (including features such as syntax highlighting, intellisense, quickhelp, and context-sensitive help)

• Project, screen, and uninstall events

• Adding and removing actions

• Scripting basics, such as using a variable, adding an if statement, testing a numeric value, using a for loop, and creating functions

• Global functions

• Plugins

• External script files

What are Actions?

Actions are what you use in Setup Factory when you want to get something done. Actions are specialized commands that your installer can perform at runtime. Each action is a short text instruction that tells the installer to do something—whether it's to open a document, download a file from the web, create a shortcut, or modify a registry key.

Actions are grouped into categories like "File" and "Registry." The category and the name of the command are joined by a decimal point, or "dot," like so: File.Run, Registry.GetValue. The text "File.Run" essentially tells Setup Factory that you want to perform a "Run" command from the "File" category…a.k.a. the "File.Run" action.

Tip: The period in an action name is either pronounced "dot," as in "File-dot-Open," or it isn't pronounced at all, as in "File Open."

By default Setup Factory handles the most common installation needs without you ever having to add additional actions. As a result you will only need to use actions when you want to supplement the basic behavior and handle advanced installation tasks. Actions let you customize what Setup Factory does for you automatically so that you can meet your installation needs exactly.

In other words, actions let you customize your installation to perform any task that it does not already perform by default. You can use actions to call functions from DLLs, submit data to a website, start and stop programs, get the amount of free space on a drive, and much more.

Note: You can find a complete list of actions in the Setup Factory help file under Program Reference > Actions.

It's worth noting that the pre-made screens in Setup Factory actually use actions to accomplish their tasks! As a result, if a screen does not accomplish some additional task and you would like to modify its build-in functionality, you can do so simply by editing the screen's actions. The power is in your hands!

The Action Editor

The action editor is where you create and edit your actions in the Setup Factory design environment. In general you can expect to find an action editor for every event in Setup Factory.

Essentially the action editor functions like a text editor by allowing you to type the actions that you want to use.

However, while it may function like a text editor, the action editor has powerful features that make it closer to a full-fledged programming environment. Some of these features include syntax highlighting, intellisense, quickhelp and context-sensitive help.

One of the most important features of the action editor is the action wizard. The action wizard provides an easy dialog-based way to select, create and edit actions without ever having to type a line of script.

The action editor gives you the best of both worlds: pure scripting capabilities for advanced users and programmers, and the easy-to-use action wizard interface for those who'd rather not use free form scripting.

Programming Features

As mentioned briefly above, the action editor provides some powerful features that make it a useful and accessible tool for programmers and non-programmers alike. Along with the action wizard (covered later under Adding Actions), the four most important features of the action editor are: syntax highlighting, intellisense, quickhelp and context-sensitive help.

Syntax Highlighting

Syntax highlighting colors text differently depending upon syntax. This allows you to identify script in the action editor as an operator, keyword, or comment with a quick glance.

Note: You can customize the colors used for syntax highlighting via the action editor settings. The action editor settings are accessed via the advanced button: Advanced > Editor Settings.

Intellisense

Intellisense is a feature of advanced programming environments that refers to the surrounding script and the position of the cursor at a given moment to provide intelligent, contextual help to the programmer.

Intellisense is a term that has been used differently by different programs. In Setup Factory, intellisense manifests itself as two features: autocomplete, and the autocomplete dropdown.

Autocomplete is the editor's ability to automatically complete keywords for you when you press Tab. As you type the first few letters of a keyword into the action editor, a black tooltip will appear nearby displaying the whole keyword. This is the intellisense feature at work. Whenever you type something that the intellisense recognizes as a keyword, it will display its best guess at what you are typing in one of those little black tooltips. Whenever one of these tooltips is visible, you can press the Tab key to automatically type the rest of the word.

Another feature of intellisense is the autocomplete dropdown. By pressing Ctrl+Space while your cursor is in the code window, a drop-down list will appear containing the names of all of actions, constants and global variables. You can choose one of the listed items and then press Tab or Enter to have it automatically typed.

Note: This dropdown cannot be accessed if your cursor is inside a set of quotes (a string).

The autocomplete dropdown is also available for completing action names after the category has been typed. For example, when you type a period after the word File, the intellisense recognizes what you've typed as the beginning of an action name and presents you with a drop-down list of all the actions that begin with "File."

The word will automatically be typed for you if you choose it and then press Tab or Enter. However, you don't have to make use of the dropdown list; if you prefer, you can continue typing the rest of the action manually.

Quickhelp

Once you've typed something that the action editor recognizes as the name of an action, the quickhelp feature appears near the bottom of the window.

Quickhelp is essentially a "blueprint" for the action that lists the names of the action's parameters and indicates what type of value is expected for each one. In the case of our Screen.Jump action, the quickhelp looks like this:

Screen.Jump(string ScreenName)

The quickhelp above indicates that the action Screen.Jump takes a single parameter called ScreenName, and that this parameter needs to be a string.

Remember, strings need to be quoted, so if we wanted to jump to a screen named Finish, the full action would have to be typed exactly like this:

Screen.Jump("Finish");

From this brief example, you can see how useful the quickhelp feature will be when you are working on your scripts.

Context Sensitive Help

Context sensitive help, as its name suggests, provides help for you based upon what you are currently doing. In the action editor, the context sensitive help lets you jump directly to the current action's topic help file.

For instance, if you are typing an action into the action editor and the quickhelp feature isn't giving you enough information (perhaps you would like to see an example), press the F1 key and the help file will open directly to that action's help topic.

Note: The context sensitive feature is only available when the action editor recognizes the action that the cursor is on. It is easy to know when this is the case since the action will appear in the quickhelp.

Tip: You can also click the Help button to trigger the context sensitive help feature.

Events

Events are simply things that can happen when your installation is running. For example, all screens have an On Preload event, which is triggered just before the screen is displayed. To make something happen just before the screen is displayed, you simply add an action to its On Preload event.

When an event is triggered, the actions (or "script") associated with that event will be executed. By adding actions to different events, you can control when those actions occur during the installation.

In Setup Factory there is an action editor for every event. When you add an action in an action editor, you are adding that action to the event. At run time, when that event is triggered, the action that you added will be performed.

Every installation has five main project events: On Startup, On Pre Install, On Install Error, On Post Install, and On Shutdown. These events can be thought of as bookends to the main phases of the install. There are also project uninstall events, which are identical to the project events except that they occur during the uninstall. The remainder of the events in Setup Factory are triggered by the screens.

Project Events

There are five project events. They are the main events or your installation and will be triggered before or after important stages of the installation. The project events can be found under Project > Actions.

The four project events are:

• On Startup

• On Pre Install

• On Install Error

• On Post Install

• On Shutdown

The On Startup event is the first event triggered in Setup Factory and thus occurs before any screens are displayed. This is a good place to perform pre-installation tasks, such as making sure the end user has a previous version of your installation installed, or that they haven't already run the installation once before.

The On Pre Install event is triggered just before the installation enters the install phase and begins installing files onto the end user's computer. This event is fired right after the last screen in the Before Installing screen stage is displayed.

The On Install Error event is fired when an error occurs during the setup, allowing you to handle it in a custom way. If you would like to ignore the error that just occurred, you can call the Application.IgnoreLastError action on this event to ignore the last error that occurred.

Note: This event will NOT be fired if the setup is exited through script or if the user aborted the setup.

The On Post Install event is triggered after the install phase of the installation has been completed, right before the first screen of the After Installing screen stage is displayed.

The On Shutdown event is the last event that will be triggered in your installation. It occurs after all screens in your installation have been displayed. It is your last chance to accomplish any action in your installation.

Screen Events

As covered in Chapter 3, the settings for each screen can be configured in the screen properties dialog. The screen events can be found on the Actions tab of the screen properties dialog.

Screen events are events that are triggered either by the controls on the screen or by the screen itself. Screen events are used for screen navigation (e.g. moving to the next screen), to change what is displayed on the screen (e.g. updating progress text), and to perform the task required of the screen (e.g. set the installation folder).

There are two main types of screens in Setup Factory: progress screens and non-progress screens. The majority of screens are non-progress screens, which basically means that these screens are not used to show progress.

Progress screens are used to show progress in your installation. They can be further broken down into two types of progress screens: those used in the Before Installing and After Installing screen stages, and those used in the While Installing stage. In general progress screens used in the Before and After Installing screen stages show progress that arises from actions. Progress screens that are used during the While Installing screen stage are used to show the progress of the main installation phase.

There are six events associated with non-progress screens:

• On Preload – triggered just before the screen is going to be displayed.

• On Back – when the back button is clicked.

• On Next – when the next button is clicked.

• On Cancel – when the cancel button is clicked.

• On Help – when the help button is clicked.

• On Ctrl Message – Triggered when a control on the screen fires a control message. Every time a control message event is fired, there will be event variables passed to the event to describe the message and which control fired it.

The On Ctrl Message event is where you will interact with the controls on the screens via script. For example, if you choose to add a Button screen to your setup, the On Ctrl Message event is where you will specify what each button does.

On the Buttons screen, each button will fire a control message when it has been clicked, basically saying "Hey I've been clicked!" You will then have a script in the On Ctrl Message event that will check the event variables to see which button has been clicked and the corresponding actions will be performed.

There are four events associated with progress screens used in the Before and After Installing screen stages:

• On Preload – triggered just before the screen is going to be displayed.

• On Start – fired as soon as the screen is displayed. This is where you will put all of the actions that are to occur while the progress screen is visible. The actions placed here are what will cause the progress that the progress screen is going to display.

• On Finish – triggered as soon as all of the On Start's event actions have finished executing. This will usually be used to move to the next screen.

• On Cancel – triggered when the cancel button is pressed.

There are three events associated with progress screens used in the While Installing screen stage:

• On Preload – triggered just before the screen is going to be displayed.

• On Progress – fired as progress is made during the installation phase. Event variables are passed to this event to describe which stage is triggering the progress event and other information.

• On Cancel – triggered when the cancel button is pressed.

Uninstall Events

Uninstall events are identical to the project events except that they occur during the uninstallation. You can find the uninstall events in the Setup Factory design environment under Uninstall > Actions.

The five uninstall events are:

• On Startup – the first event in the uninstallation, triggered when the uninstallation starts.

• On Pre Uninstall –right before your files are uninstalled from the end user's computer.

• On Uninstall Error - triggered when an error occurs during the setup's uninstall, allowing you to handle it in a custom way. If you would like to ignore the error that just occurred, you can call the Application.IgnoreLastError action on this event to ignore the last error that occurred.

Note: This event will NOT be fired if the setup is exited through script or if the user aborted the setup.

• On Post Uninstall – triggered right after all your files have been uninstalled from the end user's computer.

• On Shutdown – the final event in the uninstallation, fired right before the uninstallation finishes. This is your last chance to perform any actions during the uninstallation.

Note: For more information on the uninstall events, please read the project events section as though it were describing events occurring during the uninstall.

Adding Actions

In order to have an action performed when an event is triggered, you must add it to that event using the action editor.

Actions can either be typed directly, or you can use the Add Action button to start the action wizard. The action wizard is a dialog-based way for you to add actions in the action editor. It will guide you through the process of selecting your action and configuring its parameters.

Note: As you type an action, you can use the intellisense and code completion features to simplify this process.

Here is a brief example that shows how easy it is to add an action. It will explain how to add a Dialog.Message action to the On Startup event of your installation. The Dialog.Message action pops up a dialog with a message on it.

1) Start a new project and open the Actions dialog to the On Startup tab.

Start a new project and then bring up the Actions dialog by choosing Project > Actions. On the actions dialog select the On Startup tab so that you are editing the On Startup event.

2) Click the Add Action button. When the action wizard appears, switch to the Dialog application category and then click on the action called Dialog.Message.

The action wizard will walk you through the process of adding an action to the action editor. The first step is to choose a category using the drop-down list.

When you choose the "Dialog" category from the drop-down list, all of the actions in that category will appear in the list below.

To select an action from the list, just click on it. When you select an action in the list, a short description appears in the area below the list. In this description, the name of the action will appear in blue. You can click on this blue text to get more information about the action from the online help.

3) Click the Next button and configure the parameters for the Dialog.Message action.

Parameters are just values that get "passed" to an action. They tell the action what to do. For instance, in the case of our Dialog.Message action, the action needs to know what the title of the dialog and the message should be. The first parameter lets you specify the title of the dialog and the second parameter lets you specify the text that will be displayed on the dialog. For now the other parameters are not important but you should take some time to look at them and their options. By default Setup Factory will fill most parameters with defaults.

For now change the title to:

"Setup Factory"

and the text to:

"Message from Chapter 4"

Note: Be sure to include the quotes on either side of both parameters. These are string parameters and the quotes are needed for Setup Factory to properly interpret them.

Once you've set the action's parameters, click the Finish button to close the action wizard. The Dialog.Message action will appear in the action editor. Note that the parameters you provided are listed between parentheses after the action's name, in the same order they appeared in the Action wizard, separated by a comma.

4) Build and run your project. When the project starts you should see the dialog created by the Dialog.Message action.

Start the publish wizard by selecting Publish > Build from the menu, choose Web (Single File) as your distribution method and click the Next button. Build your installation to whichever folder you want and using whichever name you like. Once the build has completed successfully, make sure that you check the open output folder checkbox and then click the Finish button.

Once the folder where you built your installation appears, double-click on your setup executable to launch it. You should see the following dialog message appear:

Editing Actions

Often you will want to change a few of your actions' settings after you add them; to do this you need to edit the action. You can edit the action by typing directly into the action editor or by using the actions properties dialog.

The easiest way to bring up the actions properties dialog is by double-clicking on the action. If you prefer you can bring it up by placing the cursor in the action and then pressing the edit action button. (You can tell that the cursor is in an action when the actions function prototype appears in the quickhelp.)

Here is a quick example illustrating how to edit the Dialog.Message action that we created in the previous section.

1) Open the Actions dialog to the On Startup tab and bring up the Action Properties dialog.

Open the Actions dialog by choosing Project > Actions. Make sure that you are on the On Startup tab and that you see the Dialog.Message action created in the previous topic.

To edit the action, just double-click on it. Double-clicking on the action opens the Action Properties dialog, where you can modify the action's current parameters.

Tip: You can also edit the action’s text directly in the action editor, just like you would edit text in a word processor. For example, you can select the text that you want to replace, and then simply type some new text in.

2) Change the Type parameter to be MB_OKCANCEL and the Icon parameter to MB_ICONNONE.

Click on the Type parameter, click the select button, and choose MB_OKCANCEL from the drop-down list.

Then click on the Icon parameter, click the select button, and choose MB_ICONNONE from the drop-down list.

This will add a cancel button to the dialog (MB_OKCANCEL) and get rid of the icon (MB_ICONNONE).

Finally, click OK to finish editing the action. Notice that the changes that you made now appear in the action editor.

Constants

SW_SHOWNORMAL is a constant. A constant is a name that represents a value, essentially becoming an "alias" for that value. Constants are often used to represent numeric values in parameters. It's easier to remember what effect SW_MAXIMIZE has than it is to remember what happens when you pass the number 3 to the action.

3) Build and run your project. When the project starts, you should see the dialog created by the Dialog.Message action.

When you run your setup, a dialog will pop up. The dialog is created by the Dialog.Message action on the On Startup event of your installation. Notice that there is no icon and that a cancel button is now part of the dialog.

Getting Help on Actions

You can get help on actions in a variety of different ways in Setup Factory. As previously mentioned, when using the action wizard some text will be displayed in the bottom of the dialog describing the current action or parameter selected. You can also select the text displayed in blue text in the action wizard to receive context sensitive help.

The same holds true for the action editor itself. The quickhelp will display the current action’s function prototype. The help button to the right of the quickhelp will open the Help file directly to that action's help topic if there is a current action (as with the F1 key). The current action is simply the action that the cursor is in. If the cursor is not in an action, then there is no current action.

Note: For more information on the quickhelp, please see the Action Editor Features section above.

The Help button on the action editor can be clicked at any time to open the Setup Factory help file. Here you can view more information on the event that the actions are being added to.

The help file contains detailed information for each action available to you in Setup Factory. It is divided into two topics for each action: Overview and Examples. The overview section provides detailed information about the action while the examples section provides one or more working examples of that action.

In the overview topic, the help file will provide you with the function prototype, which serves as a definition of the action, showing what (if anything) the action returns, and the parameters and their types.

A function prototype is the definition of the action. It defines the types of all of the parameters, the type of the return value (if any), and whether or not any of the parameters have defaults.

The help file also describes each parameter in detail and what its purpose is.

If the action returns a value, then the help file will describe the return value and what it might be.

Scripting Basics

A script can be thought of as a sequence of actions. Scripting, therefore, is basically the creation of a sequence of actions. A script can contain one action or as many actions as you can type.

Although you can accomplish a lot in Setup Factory without any scripting knowledge, even a little bit of scripting practice can make a big difference. You can accomplish far more in a project with a little bit of scripting than you ever could without it. Scripting opens the door to all sorts of advanced techniques, from actions that are only performed when specific conditions are met, to functions that you can define, name and then call from somewhere else.

Using a Variable

One of the most powerful features of scripting is the ability to make use of variables. Variables are essentially just "nicknames" or "placeholders" for values that may need to be modified or re-used in the future. Each variable is given a name that you can use to access its current value in your script.

We say that values are "assigned to" or "stored in" variables. If you picture a variable as a container that can hold a value, assigning a value to a variable is like "placing" that value into a container.

You place a value into a variable by assigning the value to it with an equals sign. For example, the following script assigns the value 10 to a variable called "amount."

amount = 10;

Note: The semi-colon at the end of the line tells Setup Factory where the end of the statement is. It acts as a terminator. (No relation to Arnold, though.) Although technically it's optional—Setup Factory can usually figure out where the end of the statement is on its own—it's a good idea to get in the habit of including it, to avoid any potential confusion.

You can change the value in a variable at any time by assigning a different value to it. (The new value simply replaces the old one.) For example, the following script assigns 45 to the amount variable, replacing the number 10:

amount = 45;

...and the following script assigns the string "Woohoo!" to the variable, replacing the number 45:

amount = "Woohoo!";

Note that you can easily replace a numeric value with a string in a variable. Having a number or a string in a variable doesn't "lock" it into only accepting that type of value—variables don't care what kind of data they hold.

This ability to hold changeable information is what makes variables so useful.

Here is an example that demonstrates how variables work:

1) Start a new project and follow the steps from the Adding an action example.

Start a new Setup Factory project by selecting File > New Project from the menu. If you have any unsaved changes in your current project, Setup Factory will prompt you to save them. If the project wizard dialog comes up, simply hit cancel to get rid of it for now.

Once you have a brand new project, follow along with the three steps in the Adding an Action example.

2) In the action editor, replace the "Message from Chapter 4!" string with a variable named strMsg.

Just edit the script on the On Startup event so that it looks like this instead:

Dialog.Message("Setup Factory", strMsg);

This will make the Dialog.Message action display the current value of the strMsg variable when it is performed. Before we try it out, though, we need to assign a value to that variable somewhere.

Note: A common practice among programmers is to give their variables names with prefixes that help them remember what the variables are supposed to contain. This practice is often referred to as Hungarian notation. One such prefix is "str," which is used to indicate a variable that contains a string. Other common prefixes are "n" for a numeric value (e.g. nCount, nTotal) and "b" for a Boolean true/false value (e.g. bLoaded, bReadyToStart).

3) Insert the following text on the first line, before the Dialog.Message action:

strMsg = "Hello World!";

Remember to press Enter at the end of the line to move the Dialog.Message action to the next line. The script should look like this when you’re done:

This will assign the string "Hello World!" to the variable named strMsg before the Dialog.Message action is executed.

The On Startup event is triggered as soon as the installation begins, just before the first screen is displayed. This makes it a good place to put any initialization script, such as setting up default values or preparing variables that will be used in the installation. Another good location is the Global Functions section that will be described later.

4) Build and run your project. When the project starts, you should see the dialog created by the Dialog.Message action.

Note that the variable's name, strMsg, is nowhere to be found. Instead, the value that is currently in the variable is displayed. In this case, it's the value that was assigned to the variable in the page's On Preload event.

5) Exit the installation. In the action editor, change the value that is assigned to the strMsg variable to "Good Morning!".

Edit the On Startup script so it looks like this instead:

strMsg = "Good Morning!";
Dialog.Message("Setup Factory", strMsg);

6) Build and run your project. When the project starts, you should see the dialog created by the Dialog.Message action.

This time, the message looks like this:

As you can see, you've just changed the message without even touching the Dialog.Message action.

Now imagine if you had the same or similar Dialog.Message actions on fifty different events throughout your project, and you decided you wanted to change the text. With variables and a little planning, such changes are a piece of cake.

Adding an If Statement

The if statement gives your scripts the ability to make decisions, and do one thing or another in different circumstances.

Each if statement consists of a condition (or "test"), followed by a block of script that will only be performed if the condition is found to be true.

The basic syntax is:

if condition then
do something here
end

For example:

if age < 18 then
Dialog.Message("Sorry!", "You must be 18 to access this CD.");
Application.Exit();
end

The above script checks to see if the value in a variable named "age" is less than 18. If it is, it puts up a message saying "You must be 18 to access this CD," and then immediately exits from the application.

For example, if we set age to 17 first:

age = 17;
if age < 18 then
Dialog.Message("Sorry!", "You must be 18 to access this CD.");
Application.Exit();
end

...the block of script between the "then" and "end" keywords will be performed, because 17 is less than 18. In this case, we say that the if statement’s condition "passed."

However, if we set age to 20:

age = 20;
if age < 18 then
Dialog.Message("Sorry!", "You must be 18 to access this CD.");
Application.Exit();
end

...the block of script between the "then" and the "end" isn't performed, because 20 isn't less than 18. This time, we say that the if statement's condition "failed."

Note: An if statement's condition can be any expression that evaluates to true or false.

Let's modify the script on our project's On Startup event to only display the message if it is "Hello world!"

1) Open the On Startup event and edit the script to enclose the Dialog.Message action in an if statement, like this:

strMsg = "Good Morning!";
if strMsg == "Hello World!" then
Dialog.Message("Setup Factory", strMsg);
end

The double equals compares for absolute equality, so this if statement's condition will only be true if strMsg contains "Hello World!" with the exact same capitalization and spelling.

Tip: An easy way to add an if statement on the action editor is to highlight the line of text that you want to put "inside" the if, click the Add Code button, and then choose "if statement" from the menu. An if statement "template" will be added around the line that you highlighted. You can then edit the template to fit your needs.

2) Press F7 to build your project. When the build is complete, launch the setup to trigger the script.

This time nothing happens because strMsg is still set to "Good Morning!" in the first line of the On Startup event. "Good Morning!" doesn't equal "Hello World!" so the if condition fails, and the block of code between the "then" and "end" keywords is skipped entirely.

3) Exit from the setup. Edit the On Startup script to change the == to ~=.

The script should look like this when it's done:

strMsg = "Good Morning!";
if strMsg ~= "Hello World!" then
Dialog.Message("Setup Factory", strMsg);
end

The tilde equals (~=) compares for inequality (does not equal), so this if statement's condition will only be true if strMsg contains anything but "Hello World!" with the exact same capitalization and spelling.

4) Build and execute the project.

This time, because strMsg contains "Good Morning!", which is definitely not equal to "Hello World!", the message will appear.

The == and ~= operators are fine when you want to check strings for an exact match. But what if you're not sure of the capitalization? What if the variable contains a string that the user typed in, and you don't care if they capitalized everything correctly?

One solution is to use an old programmer’s trick: just convert the contents of the unknown string to all lowercase (or all uppercase), and do the same to the string you want to match.

Let's modify our script to ask the user for a message, and then display what they typed, but only if they typed the words "hello world" followed by an exclamation mark.

5) Exit from the installation. Edit the project's On Startup script to look like this:

strMsg = Dialog.Input("", "Enter your message:");
if String.Upper(strMsg) == "HELLO WORLD!" then
Dialog.Message("Setup Factory", strMsg);
else
Dialog.Message("Um...", "You didn't type Hello World!");
end

The first line uses a Dialog.Input action to pop up a message dialog with an input field that the user can type into. Whatever the user types is then assigned to the strMsg variable.

In the if statement's condition, we used a String.Upper action to convert the contents of strMsg to all uppercase characters, and then compare that to "HELLO WORLD!".

We've added an "else" keyword after the first Dialog.Message action. It basically divides the if statement into two parts: the "then" part, that only happens if the condition is true; and the "else" part, that only happens if the condition is false. In this case, the else part uses a Dialog.Message action to tell the user that they didn't type the right message.

6) Build and run the setup. Try typing different messages into the input field by closing and re-running the setup.

Depending on what you type, you'll either see the "hello world!" message, or "You didn't type Hello World!".

Note that if you type some variation of "hello world!", such as "hello world!", or "hEllO WorlD!", the capitalization that you type will be preserved in the message that appears. Even though we used a String.Upper action to convert the message string to all uppercase letters in the if statement's condition, the actual contents of the variable remain unchanged. When the String.Upper action converts a value to all uppercase letters, it doesn't change the value in the variable...it just retrieves it, converts it, and passes it along.

Now you know how to compare two strings without being picky about capitalization.

Note: Programmers call this a case-insensitive comparison, whereas a comparison that only matches perfect capitalization is considered case-sensitive.

Tip: You can also use a String.CompareNoCase action to perform a case-insensitive comparison.

Testing a Numeric Value

Another common use of the if statement is to test a numeric value to see if it has reached a certain amount. To demonstrate this, let's create another script that will stop your installation from running after it has been run on the same system more then 5 times.

1) Add the following script to a new project's On Startup event:

nRuns = Application.LoadValue("SUFUsersGuide", "Chapter4");
if nRuns == "" then
nRuns = 0;
end

nRuns = nRuns + 1;

Application.SaveValue("SUFUsersGuide", "Chapter4", nRuns);

if nRuns>5 then
Dialog.Message("Sorry!", "Setup has been run: ".. nRuns
.. " times and will exit");
Application.Exit();
end

The first line tries to read an application value using the Application.LoadValue action. It stores the result in a variable named nRuns.

The second line tests the return value of the Application.LoadValue action. If a blank string has been returned ("") then this is the first time that the setup has been executed on this computer. As a result the third line then assigns a value of 0 to nRuns. The fourth line simply completes the if statement.

The fifth line adds 1 to the current value contained in the variable nRuns, and the sixth line saves that number using the Application.SaveValue action.

The rest of the script is just an if statement that tests whether the value of nRuns is greater than 5, displays a message when that's true, and then exits the installation.

We used the concatenation operator to join the current value of nRuns to the end of the string "Setup has been run: " and then used them again to add the string " times and will exit" to the end. Note that this string has a space at the end of it, so there will be a space between the colon and the value of nRuns. (The resulting string just looks better that way.)

The concatenation operator consists of two periods, or dots (..). In fact, it's often referred to as the "dot-dot" operator. It is used to join two strings together to form a new, combined string. It's kind of like string glue.

Note: Technically, the value inside nRuns isn't a string—it's a number. That doesn't really matter, though. When you're doing concatenation, Setup Factory will automatically convert a number into the equivalent string, as required.

2) Build the project and then run it six times.

Each time you run the project the value of nRuns will be loaded, incremented by one, and then saved again. After you have run the setup six times (and all times after that) the message will appear and the installation will stop.

There you go. You've just created a pretty sophisticated little program.

Using a For Loop

Sometimes it's helpful to be able to repeat a bunch of actions several times, without having to type them over and over and over again. One way to accomplish this is by using a for loop.

The basic syntax of the for loop is:

for variable = start,end,step do
do something here
end

For example:

for n = 10,100,10 do
Dialog.Message("", n);
end

The above script simply counts from 10 to 100, going up by 10 at a time, displaying the current value of the variable n in a dialog message box. This accomplishes the same thing as typing:

Dialog.Message("", 10);
Dialog.Message("", 20);
Dialog.Message("", 30);
Dialog.Message("", 40);
Dialog.Message("", 50);
Dialog.Message("", 60);
Dialog.Message("", 70);
Dialog.Message("", 80);
Dialog.Message("", 90);
Dialog.Message("", 100);

Obviously, the for loop makes repeating similar actions much easier.

Note: If the step is missing from the for loop, it will default to 1.

Let's use a simple for loop to add all of the digits between 1 and 100, and display the result.

1) Start a new project and add the following script to the project's On Startup event:

n = 0;
for i = 1, 100 do
n = n + i;
end

Dialog.Message("", "The sum of all the digits is: "
 .. n);

The first line creates a variable called n and sets it to 0. The next line tells the for loop to count from 1 to 100, storing the current "count" in a variable named i.

During each "pass" through the loop, the script between the "do" and the "end" will be performed. In this case, this consists of a single line that adds the current values of n and i together, and then stores the result back into n. In other words, it adds i to the current value of n.

This for loop is the same as typing out:

n = n + 1;
n = n + 2;
n = n + 3;
n = n + 4;

...all the way up to 100.

The last line of our script displays only the result of the calculation to the user in a dialog message box.

Tip: You can use the Add Code button to insert an example for loop, complete with comments explaining the syntax. You can then edit the example to fit your own needs.

2) Build and run the setup.

When you run the setup, the for loop will blaze through the calculation 100 times, and then the Dialog.Message action will display the result.

It all happens very fast.

3) Exit the setup.

You probably won't find yourself using for loops as often as you'll use if statements, but it's definitely worth knowing how to use them. When you need to repeat steps, they can save you a lot of effort.

Of course, when it comes to saving you effort, the real champions are functions.

Creating Functions

A function is just a portion of script that you can define, name and then call from somewhere else.

You can use functions to avoid repeating the same script in different places, essentially creating your own custom "actions"—complete with parameters and return values if you want.

In general, functions are defined like this:

function function_name (arguments)
function script here
return return_value;
end

The "function" keyword tells Setup Factory that what follows is a function definition. The function_name is simply a unique name for the function. The arguments part is the list of parameters that can be passed to the function when it is called. It's essentially a list of variable names that will receive the values that are passed. (The resulting variables are local to the function, and only have meaning within it.) A function can have as many arguments as you want, even none at all.

The "return" keyword tells the function to return one or more values back to the script that called it.

The easiest way to learn about functions is to try some examples, so let's dive right in.

1) Start a new project and then choose Resources > Global Functions.

This opens the resources dialog to the global functions tab.

The global functions section is a convenient place to put any functions or variables that you want to make available throughout your project. Any script that you add to this section will be performed when your application is launched, right before the project's On Startup event is triggered.

2) Type the following script into the Global Functions tab, then click OK to close the dialog:

function SayHello(name)
Dialog.Message("", "Hello " .. name);
end

This script defines a function named SayHello that takes a single argument (which we've named "name") and displays a simple message.

Note that this only defines the function. When this script is performed, it will "load" the function into memory, but it won't actually display the message until the function is called.

Once you've entered the function definition, click OK to close the Global Functions dialog.

3) On the project's On Startup event add the following script:

SayHello("Mr. Anderson");

This script calls the SayHello function that we defined on the global functions section, passing the string "Mr. Anderson" as the value for the function's "name" parameter.

4) Build and run the setup.

When you run the setup, the script on the On Startup event calls the SayHello function, which then displays its message.

Note that the SayHello function was able to use the string that we passed to it as the message it displayed.

5) Exit the setup. Choose Resources > Global Functions, and add the following script below the SayHello function:

function GetName()
local name = Dialog.Input("", "What is
 your name:");
return name;
end

When you're done, click OK to close the dialog.

This script defines a function called GetName that does not take any parameters. The first line inside the function uses a Dialog.Input action to display a message dialog with an input field on it asking the user to type in their name. The value returned from this action (i.e., the text that the user entered) is then stored in a local variable called name.

The "local" keyword makes the variable only exist inside this function. It's essentially like saying, "for the rest of this function, whenever I use 'name' I'm referring to a temporary local variable, and not any global one." Using local variables inside functions is a good idea—it prevents you from changing the value of a global variable without meaning to. Of course, there are times when you want to change the value of a global variable, in which case you just won't use the "local" keyword the first time you assign anything to the variable.

The second line inside the function returns the current value of the local "name" variable to the script that called the function.

Tip: We could actually make this function's script fit on a single line, by getting rid of the variable completely. Instead of storing the return value from the Dialog.Input action in a variable, and then returning the contents of that variable, we could just put those two statements together, like so:

function GetName()
    return Dialog.Input("", "What is your name:");
end

This would make the GetName function return the value that was returned from the Dialog.Input action, without storing it in a variable first.

6) Edit the script in the project's On Startup event so it looks like this instead:

strName = GetName();
SayHello(strName);

The first line calls our GetName function to ask the user for their name, and then stores the value returned from GetName in a variable called strName.

The second line passes the value in strName to our SayHello function.

7) Build and launch the setup.

When the setup begins the On Startup script will automatically be executed and the input dialog will appear, asking you to enter your name.

After you type in your name and click OK (or press Enter), a second dialog box will appear, greeting you by the name you entered.

Pretty neat, huh?

8) Exit the setup. Edit the script in the project's On Startup event so it looks like this:

SayHello(GetName());

This version of the script does away with the strName variable altogether. Instead, it uses the return value from our GetName function as the argument for the SayHello function.

In other words, it passes the GetName function's return value directly to the SayHello function.

Whenever a function returns a value, you can use a call to the function in the same way you would use the value, or a variable containing the value. This allows you to use the return value from a function without having to come up with a unique name for a temporary variable.

9) Build and launch the setup again to try out the script again. When you're done, exit the setup.

The script should work exactly the same as before: you'll be asked for your name, and then greeted with it.

This is just a simple example, but it should give you an idea of what an incredibly powerful feature functions are. With them, you can condense large pieces of script into simple function calls that are much easier to type and give you a single, central location to make changes to that script. They also let you create flexible "subroutines" that accept different parameters and return results, just like the built-in Setup Factory actions.

And despite all that power, they are really quite simple to use.

Action Resources

There are three additional resources at your disposal that can be useful when you are working with actions in Setup Factory: Global Functions, Plugins, and Script Files.

Global Functions

The Global Functions resource in Setup Factory can be found in the design environment under Resources > Global Functions. The Global Functions resource is an action editor that will let you enter script.

The script in the global functions section will be loaded into the installation before the On Startup event is executed. This makes it a great place to create any functions that you want to have available during your install and a great place to initialize any global variables.

Note that any script in the Global Functions resource will be executed, so it is generally best to only use it for variable initialization and function declarations. It is a good idea to place all other scripts on events within your setup.

Note: Since the global function section is normally used to create global functions and initialize global variables, the script that is contained there is sometimes referred to as global script.

Plugins

Plugins are actions that are external to the Setup Factory program. They are independently developed and distributed and can be integrated into your projects to extend their functionality. Some plugins may be developed by Indigo Rose, while others may be developed by third parties.

You can refer to the action plugin's documentation (click the About Plugin button after adding it) for information on what features it adds and how to use them.

Plugins can be added or removed from your project on the Plugins tab, which can be accessed by choosing Resources > Plugins in the Setup Factory design environment.

Note: Any action plugins that are located in Includes\Plugins within the Setup Factory program directory and that were created with version 2.0 (or higher) of the Plugin SDK will be available through the design environment by choosing Resources > Plugins... from the program menu and clicking the Add button.

Note: Action plugins may be available in either 32-bit or 64-bit. You must ensure you choose the version of the plugin that matches your intended setup platform (32-bit or 64-bit). The setup platform can be set on the Setup File tab of the Build Settings dialog (Publish > Settings).

The More Plugins button is an easy way to see what plugins are currently available on the Indigo Rose web site. Pressing this button will bring you to the Setup Factory plugins area of the Indigo Rose web site.

If a plugin has been added to the plugins tab, it will be included in your setup. Since there is some overhead in terms of file size, it is recommended that you only include plugins that are needed by your installer.

Once you have added the plugin to your project all of its actions will be available to you in the action editor and action wizard.

Note: Help for plugin actions can be accessed on the action editor in the same way that you would access help for built-in actions.

Script Files

Script files are external text files that contain Lua script usually with the .lua file extension. Script files can be added to your project on the script files tab of the resources dialog which can be found under Resources > Script Files.

Note: All action editors in Setup Factory have the ability to export their script via the advanced button. Select Advanced > Save to save the script as an external file.

Script files are very similar to the global functions section of Setup Factory except that instead of the script being kept in the Global Functions resource, it is stored externally to your project on a text file.

Script files are very useful if you share important and complex code between a variety of different projects.

Here is a quick comparison of the differences between sharing script between projects using the Global Functions resource versus script files.

If you have some script that you want to share between many projects using the Global Functions resource, you have to copy and paste the script into each setup that needs it. Now each project has an exact copy of the script.

The method works fine until you discover a bug or want to change some of the code. Since each project contains a copy of the script, you will have to edit the script in each project in order to be sure that it is using the correct code.

If you were to use an external script file, you need to develop a working piece of script and then get that script into a text file. Then, include the script file in each project that needs it. Using this script file method, each project does not contain a copy of the script; rather, each project references the same piece of script.

If you find an error or want to change any of the script, you do not have to edit the script in each project; you simply have to edit the script in the text file. Since each project references the same script file, you know that the next time you build a project, it will be using the correct script.

Essentially, with the Global Functions resource, you have to maintain the script for each project that uses it. On the other hand, the script file method allows you to maintain your script in a single location, the script file. For this reason, it's a good idea to use script files when you want to share global script between several projects.


Chapter 5: Session Variables

Session Variables

When designing an installer, it's often desirable to make parts of it dynamic. During the development and maintenance stages, there is usually some information that will need to change, such as your product's version number. Being able to quickly propagate such changes throughout the project can greatly decrease development time and costs. If you can predict such changes ahead of time, you can minimize their impact by using session variables as "placeholders" for the data that is likely to change.

There are also some things that are almost guaranteed to be different from one system to the next, such as the path to the user's My Documents folder, or what drive they installed Windows on. Your installer must be flexible enough to handle all the ways a user can customize a system.

Having a dynamic installation at run time is equally important. For example, if you want to allow the user to choose the destination folder, this means that all files must be dynamically installed to the chosen location.

Session variables are designed to handle such dynamic data during the installation. In this chapter you will learn everything there is to know about session variables in Setup Factory.

In This Chapter

In this chapter, you'll learn about:

• Built-in and custom session variables

• Setting session variables

• Adding session variables

• Removing session variables

• Using session variables on screens

• Expanding session variables

What Are Session Variables?

Session variables are special named "containers" for values that may change during the installation process. At run time these variables are automatically replaced with the string of text that is assigned to them. These variables are used when displaying dynamic text on screens or within the paths of files you are installing.

Even though all session variables behave the same, there are two categories of session variables that can be used in Setup Factory: built-in session variables, and custom session variables.

Built-in Session Variables

For convenience, Setup Factory contains a series of built-in session variables that are commonly used in projects. These variables are automatically expanded every time they're used.

Many of the built-in session variables hold information that has been gathered from the user's system. For example, since the path to the Windows folder can differ between systems, a session variable named %WindowsFolder% is provided, and it automatically contains the correct path. The list of built-in variables is too long to outline here, but some other examples include %ProgramFilesFolder% and %MyDocumentsFolder%.

While many of the built-in variables gather information from the target system, there are other built-in session variables that are available for managing information about the product you are installing. A few examples of these product-related variables are:

• %ProductName% - The name of the product you are installing.

• %CompanyName% - The name of the company that developed the product.

• %ProductVer% - The version of the product you are installing.

• %AppFolder% - The default directory that the product will be installed to.

Custom Session Variables

Since the built-in session variables were designed to be generic, there may be situations where the available built-in session variables do not accomplish all of your design needs. For these occasions, you can still take advantage of session variable technology by defining custom session variables in your install. These can be named anything you wish and can contain any textual data you require.

Setting Session Variables

Each session variable consists of a name, e.g. "%NickName%," and a value that you assign to it, e.g. "Pookie." When a session variable is expanded at run time, its name is replaced by the value that is currently assigned to it. (For example, "I love you, %NickName%" would become "I love you, Pookie.")

There are two ways you can assign a value to a session variable: you can set its initial value on the Session Variables tab, or you can use an action to set its value anywhere in your installation.

Using the Session Variables Tab

Generally the Session Variables tab is used for setting the initial value of session variables at startup and for values that won't be changing at run time using actions.

The Session Variables tab can be found on the Project Settings dialog. To display this tab, choose Project > Session Variables from the program menu. An image of this dialog can be seen below:

As seen in the image above, the Session Variables dialog contains three categories: Product Information, Folder Defaults, and Custom.

The Product Information category contains a series of built-in session variables whose values can be set. They consist of informational values that pertain to the product you are installing. To set the value of one of these variables, click on the value in the right-hand column that is beside the session variable whose value you want to set. The session variable will become highlighted and the cursor will flash in the variable's value field. This means it is ready for editing. Once you have finished editing its value, you can press the Enter key, or click on the next variable you wish to edit.

The Folder Defaults category contains two built-in variables that are used as defaults, both relating to the files you are installing. For example, the variable %AppFolder% contains the default path that will be used as the destination for your files (if they are being installed to that location).

The Custom category contains any custom session variables that have been created. Variables of this type will appear in the same way as variables in the other two categories.

Tip: As the session variable list grows, it may help to hide portions of the list. Each category can be expanded or collapsed by clicking the "+" icon on the left hand side of the category text.

Using Actions

An action is also available to set the value of a session variable. This action is called SessionVar.Set and can be found in the "SessionVar" action category. It allows you to set the value of an existing session variable that was defined on the Session Variables tab, or to create a new one.

The SessionVar.Set action can be used with any event (i.e. on any Actions tab) throughout the project. The function prototype for this action is:

SessionVar.Set(string VariableName, string Value)

For example, if you want to assign the value "My Value" to a session variable named %MyVar%, the action would look like this:

SessionVar.Set("%MyVar%", "My Value");

After the above action is performed, all occurrences of the text %MyVar% on future screens will be replaced with the text "My Value."

Note: The SessionVar.Set action works with all session variables, i.e. both custom and built-in session variables. It is possible to overwrite a built-in session variable's value using the SessionVar.Set action, so be very careful when setting session variables with actions. Under normal circumstances, there should be no reason to modify the values of built-in variables.

Adding Session Variables

When you add a new session variable to your project and assign it a value, it is ready to be used on any screen or file path in your project.

Adding a new session variable to your project means that its name is now a special placeholder for the string that was assigned to it. As with built-in variables, custom session variables can be used on any install screen or within the path of any file in your project's file list.

There are two methods you can use to add custom session variables to your project: using the Session Variables tab, or using an action.

Using the Session Variables Tab

To add a new session variable to your project, choose Project > Session Variables from the program menu. This will display the Session Variables tab on the Project Settings dialog.

When setting a session variable from this tab, its value is available as soon as the install starts and throughout the install. The only difference between a custom session variable and a built-in one is that you can remove custom session variables from the Session Variables tab, but you cannot remove built-in ones.

To add a new session variable to your project, you can also click the Add button. This will display the New Session Variable dialog where you can define its name and assign it a value. When you click the OK button on the dialog, the newly defined session variable will appear in the Custom category of the list.

Using Actions

An action can also be used to create new session variables. As mentioned earlier in the chapter, this action is called SessionVar.Set and can be found in the "SessionVar" action category. This allows you to create a new session variable at any point during the install. The function prototype for this action can be found below:

SessionVar.Set(string VariableName, string Value)

For example, if you want to create a new session variable called %MyVar% and assign it the value "My Value," the action script would look like the following:

SessionVar.Set("%MyVar%", "My Value");

Note: Generally it is good practice to create new session variables on the Session Variables tab rather than using an action. Following these guidelines helps keep track of which variables exist in the install.

Removing Session Variables

When you remove a session variable from your project, Setup Factory will no longer recognize the variable's name as special placeholder text. For example, removing the session variable %ProductName% causes the name to revert back to its actual characters. In other words, the text "%ProductName%" ceases to be anything other than the letters %, P, r, o, d, u, c…and so on. After the session variable is "removed," there is no longer a value associated with the name, and no expansion occurs.

There are two methods for removing session variables from your project: using the Session Variables tab, or using actions.

Using the Session Variables Tab

Similar to adding session variables, removal of session variables can also be accomplished from the Session Variables tab. However, only those within the Custom category can be removed from your project. To remove a custom session variable, click on the desired session variable name in the list to highlight it, and then click on the Remove button. The session variable will be removed from the list.

Using Actions

Session variables can also be removed at any point during your install with an action. The action used to remove a session variable is called SessionVar.Remove and can be found in the "SessionVar" action category. The function prototype for this action can be seen below:

SessionVar.Remove(string VariableName)

For example, if you want to remove a session variable called %MyVar%, the action script would look like the following:

SessionVar.Remove("%MyVar%");

Note: Since both custom and built-in session variables behave the same, it is possible to remove a built-in session variable using the SessionVar.Remove action. For this reason, extra care should be taken when removing session variables with actions.

Using Session Variables on Screens

One of the main uses of session variables is for the dynamic expansion of text strings on screens in the install. One example of a valuable use of session variables is when you need to use a value on multiple screens, such as a product version number. While you can certainly enter the text directly for each screen, if that string changes in the future, it would require finding every location it is used in order to change its value. Using a session variable in place of that text would only require the modification of the session variable's value in one location.

Another valuable use of session variables is for gathering data that needs to be displayed on other install screens. In this case, values are often not known until some point during the install, and therefore could not be directly entered at design time.

Tip: Session variables can also be useful in multilingual installs for custom messages that you wish to display depending on the language detected or chosen.

When Are Session Variables Expanded?

When an installation starts, the session variables that are defined on the Session Variables tab are recognized and ready to be expanded. Any session variable that is used on a screen will automatically be expanded before that screen is shown and before the screen's On Preload event.

If a session variable is set to a different value, it will reflect that change the next time it is used on a screen, or if it is explicitly expanded using the SessionVar.Expand action.

Expanding Session Variables

As discussed in earlier sections, session variables are automatically replaced with their contents on screens. However, since these variables are often used to gather information from the user, the resulting values stored in these variables may need to be accessed and worked with in action script. In order to retrieve the contents of a session variable while in action script, the SessionVar.Expand action must be used. The function prototype for this action can be seen below:

string SessionVar.Expand(string Text);

For example, if there is an existing session variable called %MyVar% containing the string "These are the contents of my variable," you can access this string using the following action script:

strContents = SessionVar.Expand("%MyVar%");

In the above line of script, the Lua variable strContents would contain the value within the session variable, "These are the contents of my variable".

However, SessionVar.Expand does not restrict its Text parameter to only a session variable. It can also be used to expand a string that contains a session variable. For example, passing the string "The contents of my variable are: %MyVar%" as the parameter of SessionVar.Expand would return the entire string with the expanded contents of the session variable %MyVar%.

This action not only expands the session variable, but performs a recursive expansion. This means that if the session variable being passed to the action has an assigned value that contains a session variable, that session variable will be expanded as well. This type of recursion can be any number of levels deep. Yes, this sounds confusing, but an example should help:

Given the following two existing session variables:

%Inside% - whose value is "this is the inside string"
%Outside% - whose value is "The value of inside is: %Inside%"

If the following action script was executed:

strContents = SessionVar.Expand("%Outside%");

The contents of the Lua variable "strContent" would be:

"The value of inside is: this is the inside string"

Setup Factory also contains an action that will prevent the recursive expansion of session variables. This action is called SessionVar.Get and can also be found in the "SessionVar" actions category. The function prototype can be seen below:

string SessionVar.Get(string Text);

Using the previous example, let's say we only wanted the expanded contents of %Outside%, without expanding %Inside%. In that case, the following action script could be executed:

strContents SessionVar.Get("%Outside%");

…and the contents of the Lua variable strContents would be:

"The value of inside is: %Inside%"

Tip: If you would like to see an advanced example of session variables in use, examine some of Setup Factory's built-in screens. For example, the Select Install Folder screen uses actions to set, update, and display a pair of session variables named %SpaceAvailable% and %SpaceRequired%.


Chapter 6: Packages

Packages

Applications can often contain a series of optional components that extend the functionality of the main application. Since these components are not always required, it's often desirable to allow the user the choice of what components they would like to install. While this type of design can be accomplished with a series of file conditions, it can be very tedious. Packages are designed as a grouping mechanism that allows components to be managed in an easier and more efficient way, both at design time and run time.

In This Chapter

In this chapter, you'll learn about:

• What packages are and how they can be used

• Defining packages

• Assigning files to packages

• Adding a Select Packages screen to your project

• Advanced package actions

What Are Packages?

Packages are special categories that you can define in order to group related files together. They're usually used to give users the ability to choose which parts of an application they want to install. Here’s a basic overview of packages:

• Each package consists of a unique package ID, a localized display name, and localized description.

• You can assign file or folder references to packages by using the File Properties or Folder Reference Properties dialog.

• You can have as many packages in a Setup Factory project as you want.

• You can assign as many files to a package as you want.

• You can assign the same file to more than one package.

• You can let your users select packages by adding a Select Package screen to your installer.

• Selecting a package sets its "install" property to true. Deselecting a package sets its "install" property to false. The state of this property affects whether or not all of the files assigned to the package will be installed.

• The "install" property of the package is what determines whether files are installed.

• Files assigned to multiple packages are installed when at least one of the packages' "install" properties is set to true.

• Setup Factory automatically calculates the total size of the files in each package. These package sizes can optionally be displayed on the Select Packages screen. You can also set an optional value for each package that will be added to the package size calculation.

• The name and description of a package can be localized so they will appear in the user's chosen language.

• Packages can be disabled so that they cannot be modified if used on the Select Packages screen.

Using Packages

Using packages in your Setup Factory project involves four simple steps:

1. Create the packages.

2. Localize (translate) the package's properties (only if creating a multilingual installation).

3. Assign files to the packages.

4. Add a Select Packages screen to your project so users can select the packages.

For example, let's say you include a set of tutorials with your application in the form of very large video files. Because these files are so large, you want your users to be able to choose whether or not to install them at run time. This is a situation where packages should be used.

Any files in your installation that you know will always be installed should not be assigned to a package. Packages should only be used for groups of files that are conditionally installed.

Defining Packages

In order to group files into packages, they must first be added and configured in the project. This is done using the package manager.

The Package Manager

The management of each package in your project can be done through the package manager. This configuration tool is located on the Packages dialog and can be accessed by choosing Project > Packages from the program menu.

The Packages dialog contains a visual representation of the packages currently in the project, as well as their contents. Packages can be added, removed, or edited from this dialog.

Here is an example of the Packages dialog for a project containing three packages:

Other features of the dialog include the "Show files" and "Show infotips" check boxes, both located in the top right hand corner of the dialog. The Show files option is used to show or hide the contents of each package in the list. The Show infotips option controls whether or not to display a pop-up tooltip showing the properties of the package under the mouse pointer. When this option is checked, a summary of the properties will appear whenever the mouse pointer hovers over a package ID on the Packages dialog.

Adding Packages

Adding a package to your project provides you with a category that can later be used to group any related files that you wish to optionally install. Adding packages can be accomplished through the Packages dialog. As mentioned earlier, the Packages dialog can be opened by choosing Project > Packages from the program menu. To add a new package to your project, click the Add button. This will open the Package Properties dialog as seen below:

The Packages dialog contains all of the necessary settings to create a new package in your project.

1. The first step is to enter the Package ID value. The package ID is a unique string that is used to identify the current package. It is best to use an ID that is descriptive, for example, "Bonus_Images."

2. The second piece of information to enter is the package's display name. This is the name that will be seen by the user if the package is available on the Select Packages screen.

3. The Description field can be filled with additional information to help describe the contents of the package. This information is also displayed on the Select Packages screen and is designed to help the user decide whether or not it is wanted.

4. There may be occasions when the contents of a package are within another setup, or not even within the install itself. In this situation, Setup Factory would not have access to the amount of disk space required for the files. In these cases, the Additional disk space setting is available so you can manually populate the anticipated size of the content. When each package's size is calculated at run time, this value will be added to the current size value.

5. The next step is to configure the initial states of the package. Two settings are available in this category: "Install this package" and "Allow user to change." Checking the Install this package check box tells Setup Factory that its "install" property should be initially set to true and that all of its files should be installed. Unchecking this box sets the property to false, saying that none of the package's files should be installed. The Allow user to change check box controls how this package's check box will appear in the packages tree on the Select Packages screen. If this option is checked, the user will be able to select or deselect the package. Unchecking this option greys out the package, preventing the user from changing its install state.

6. The next step is to localize the package's display name and description. This is only necessary if you are creating a multilingual installation. See the Localizing Packages topic for further information on this feature.

After the above properties have been set and you click the OK button, the package will be added to the list on the dialog.

Removing Packages

Similar to adding packages to your project, packages can also be removed. Removing a package from your project simply removes that category. No files in your project will be removed.

To remove a package, locate the one you want to remove and click on its package ID so it is highlighted. Once highlighted, you can either click the Remove button or press the Delete key. This results in the removal of the package from the list.

Editing Packages

After creating your package, you may need to update or edit some of its properties. The editing of packages can be done on the Packages dialog. To edit a package’s properties, locate the desired package ID in the list and click on it so it is highlighted. Next click the Edit button to display its settings on the Package Properties dialog.

Tip: Instead of clicking the Edit button, you can double click on the package ID to open its Package Properties dialog.

Localizing Packages

When creating multilingual installations containing packages, it's not only necessary to localize screens. Since the properties of a package such as its display name and description are visible on the Select Packages screen, those properties must also be localized so that their text is displayed in the language detected on that machine. These two properties can be localized from the Packages dialog. By localizing we mean translating the text into a specific language that is supported by the install.

In order for a package to be localized, the languages must first be configured in the project. (See Chapter 7 for more information on adding languages.) Each package can be localized from its Properties dialog. To open the package's properties, click on the package's ID in the list and click the Edit button.

At the bottom of the Package Properties dialog you will find a drop-down list containing all of the available languages that the current package's properties can be translated to. This is the language selector. When you change the value in the language selector, the Display Name and Description text values can be translated for the chosen language. For example, if English, French and German are supported by your setup, you would first select English from the dropdown and translate the two strings. Then you could select French in the dropdown and translate the two strings to their equivalent French translation. The same procedure would be used to translate the package to German.

When the package is displayed on the Select Packages screen, its display name and description will appear in the correct language—the appropriate text will be chosen according to the language that is running on the user's system.

Assigning Files to Packages

When a file is assigned to a package it means that it is now part of a collection of files that can be selected at run time. If that package is selected, all files that have been assigned to it will be installed.

Assigning a file to a package can be done through each file's Properties dialog. The following steps can be taken to add a file to a package:

1. Find a file in the main file list that you want to assign to a package.

2. Right click on the target file and select "File Properties…" from the context menu to open the file's Properties dialog. You can also double click the file to accomplish the same result.

3. Click on the Packages tab.

The packages tab will look similar to the example below:

The packages tab lists all of the current packages defined in the project, each by their package ID. Each package will also contain a check box used to determine whether or not the current file belongs to that package. A file can belong to zero or more packages.

Tip: Multiple files can be assigned to a package at once using the Multiple File Properties dialog. Once a group of files is selected, choosing File Properties from the right-click context menu will open the Multiple File Properties dialog. When checking a package on the Packages tab, each file that has been initially selected will belong to the selected package.

If you were to go back to the package manager, each package will optionally display the files that have been assigned to them.

Adding a Select Packages Screen

After each package has been created and all of the desired files have been assigned to them, it is time to add a Select Packages screen to the install. While there are other methods of interacting with packages, the select packages screen was designed to present a user-friendly interface for selecting packages.

The Select Packages screen is normally placed before the Select Install Folder screen, located on the Before Installing screen stage. This will allow the selected package to be part of the file size that is calculated on the Select Install Folder screen. The following steps can be taken to add a Select Packages screen:

1. Choose Project > Screens from the program menu to open the Screens dialog.

2. Click on the Before Installing tab.

3. Click the Add button to open the Screen Gallery dialog.

4. The screen gallery contains an alphabetic list of all of the screens that can be added to your install. Locate the Select Packages screen, highlight it, and click the Ok button. This will add the selected screen to the screen list.

5. While the Select Packages screen is highlighted, keep clicking the up arrow button to move the screen one position up in the list until it is before the Select Install Folder screen.

Screen Properties

The Select Package screen's Properties dialog can be opened by highlighting it in the Before Installing list and clicking the Edit button. The settings that are used to configure the displaying of packages can be found on the Settings tab. An example of the dialog can be found below:

The Show total size check box controls whether or not Setup Factory will automatically calculate and display the amount of disk space the installation requires for the selected package, along with a text description.

Note: By default the text used is "Space required by setup: %SpaceRequired%." %SpaceRequired% is a custom session variable defined on this screen which will be replaced by the actual required space value at run time.

The Select Packages section of the dialog contains the settings that are used to determine what the user will see at run time. The area in the bottom right labeled "Packages:" contains the list of packages that are currently being used in the install; you will most likely want to make this visible to the user.

On the left is a section labeled "Tree:" This section is the framework for a selectable tree structure that will be used to represent the packages in your install.

Tip: You can also open the screen's Properties dialog by double-clicking it.

Adding Packages to the Tree

Any packages that you want to make available on the screen at run time must first be added to the tree. To add a package to the tree, highlight its package ID in the Packages section on the right-hand side and then click the Add button (represented by an arrow pointing to the left). This will add the package to the tree on the left.

This procedure can be replicated for each package that you want to display in the tree.

Grouping Packages into Categories

Since packages can only contain files, there must be another element if the goal is to present a hierarchy of selectable options. The element that accomplishes this type of design is called a "category."

A category is designed to group a number of packages and/or other categories together in a select package tree. If a parent category is selected by the user, all of the packages and categories within it will be selected as well.

Creating Categories

To add a category to the package tree, click the Add button to display the Category Properties dialog. The Category Properties dialog contains several settings that control its appearance and functionality in the tree, such as the category’s display name and description.

The defaults section of the properties is similar to those of a package's properties. The Install check box controls its initial state. If it is checked, all of its contents will be checked and if unchecked, all of its contents will be unchecked. The Enabled check box controls whether or not it can be changed by the user. The Expanded check box controls whether or not the category's contents will initially appear expanded.

Organizing the Tree

Once the desired packages and categories have been added to the tree, you will then need to organize them into the structure you want your users to see. As mentioned earlier, a category can contain packages or other categories. Both packages and categories can be moved up and down using the up arrow and down arrow buttons.

In order to add a package to a category, you would move the package so it is below the target category. Then while it is still highlighted, click the button with the arrow pointing right. To remove a package from a category, you would instead click the button with the arrow pointing to the left.

Below is a sample of how the tree will look after a package has been added to a category:

Here is a sample of how the above settings would appear to the user at run time:

You can remove a package or category from the tree by clicking the Remove button. Removing a package from the tree only removes its representation in the tree. The package itself will not be removed from your install.

Advanced Package Actions

While the Select Packages screen handles the normal situation while working with packages, there may be occasions where you wish to handle things in a highly customized way. For this reason there are a few actions that are available for getting and setting package properties.

SetupData.GetPackageList

This action enables you to get a list of all package IDs in the setup. When called, it returns a numerically indexed table of the package IDs.

SetupData.GetPackageProperties

This action allows you to get all of the available information about a particular package, which is stored in a table. For example, let's say that you need to know whether a certain package is set to be installed at a certain point during the install. The following action script could be used to gather this information:

tbMyTable = SetupData.GetPackageProperties(My_PackageID);
bIsInstalled = My_PackageID.Install;

In the above script, the variable bIsInstalled will contain true if the package is set to be installed, or false if it is not. Other properties that are available are its display name, description, additional disk space value and enabled state.

SetupData.SetPackageProperties

This action is similar to Setup.GetPackageProperties. However instead of retrieving information about a package, you can set its properties at runtime. For example, if you wanted to explicitly set a package so its contents will be installed, you could use the following action script:

tbMyTable = {Install=true};
SetupData.SetPackageProperties(My_PackageID, tbMyTable);

The above action script first creates a table with the desired index value. The next action takes that table and merges its values with the specified package's current settings.

These types of actions may be useful in cases where the install states of packages are not controlled by user interaction, but rather a series of queries of the user's system.

Tip: Another use for these actions could be to control the tree in a custom way when the user selects a particular option. For example, you could automatically turn a specific package on whenever another specific package was turned off.


Chapter 7: Languages

Languages

The Internet has opened many new markets to software developers whose past products would have usually only supported their own local language. Today, even smaller software development and data distribution companies have realized the need to provide multilingual software to meet existing and newly emerging international software markets.

One of Setup Factory's strongest features is its support for creating foreign language installations. You can use Setup Factory to create an installer that will automatically display messages and prompts in your user's native language.

Setup Factory ships with display messages and prompts in many of the world's most commonly used languages. It also makes it very easy to modify existing translations at any time.

In This Chapter

In this chapter, you'll learn about:

• Internationalizing your installer

• How run-time language detection works

• The language manager

• Language files

• Setting the default language

• Adding and removing languages

• The language selector

• Localizing screens, packages, the uninstaller, and actions

• Customizing error messages and prompts

• Advanced techniques, such as using actions to determine the current language and "changing" the current language for testing purposes

Internationalizing Your Installer

Setup Factory has the ability to automatically detect the user's system's language and to display messages and screens in that language. The developer has full control over what languages are supported in their setup and the content that they would like to present to the user.

Language text is mainly used for messages generated throughout the install and on screens, both of which can be easily translated for multilingual installs.

Setup Factory allows you to localize your setup application in three areas:

· Error messages, status messages and prompts that are common to all setups.

· Screens that appear as the main GUI of the installation that are usually application-specific.

· Packages used by the setup to organize files into logical units.

The following sections of this chapter will look more closely at how to provide international support to all of these areas of the install.

Run-time Language Detection

At run time, the language that Setup Factory detects is based on the user's regional and language settings. These settings allow Windows users to configure which language is displayed, which input locale is used and which keyboard layout is supported in the Windows operating system environment. These settings are usually configured when Windows is installed and can usually be changed from the Windows Control Panel. For example, in Windows XP, a user can select Start > Settings > Control Panel and start the Regional and Language Settings control panel application.

Each language in Windows has a constant language identifier. A language identifier is a standard international numeric abbreviation for the language in a country or geographical region made up of a primary and secondary language ID (there is a complete list of primary and secondary language IDs in the Setup Factory help file). Setup Factory maps all known languages and sub-languages according to the language identifier used for that language by Windows.

Tip: Setup Factory maps language identifiers to language names in a file called language_map.xml located in Setup Factory's Language folder (usually "C:\Program Files\Setup Factory 9\Languages"). You can look at this file to see which primary and secondary language IDs are mapped to which languages. It is NOT recommended that you modify this file unless you have a very specific reason to do so.

The Language Manager

The languages that are supported by your setup are all configured from the Language Manager. You can access the language manager by selecting Project > Languages from the menu.

Although you can localize messages in several areas of the design environment, the Language Manager is the only place where you can control the setup's default language as well as which languages are or are not supported by your setup. For example, if you are editing one of your screens and decide that you would like to add German support to your setup, you will have to use the Language Manager to do so. Once you add German support here, it will also be available to all other areas of the setup.

When you add a language to your project, you are indicating that you want the setup to recognize that particular language identifier on a user's system and use specific messages for that language when identified. Conversely, if a language is not represented in the languages list, it does not mean that the setup will not run on a system that uses that language; it simply means that it will use the default language in that case.

Default Language

Every setup must have a default language. The default language is the one that will be used whether the user happens to be using the default language or any other language not represented in the languages list.

For example, let's suppose that you have English, French and German support in your setup with English as the default language. If your user runs the setup on a Greek system, the user will see the English messages since you did not specifically include support for the Greek language.

Note that the default language must be one that has a corresponding language file (see the next section).

Language Files

A language file is an XML file that contains all error messages, status messages and prompts that are used internally by the setup. Language files do not contain setup-specific messages such as those used on screens and packages. Note that not all languages have a pre-configured language file.

Language files are located in Setup Factory's Languages folder (usually "C:\Program Files\Setup Factory 9\Languages"). They are named according to the English name for the language they represent. Each file contains a language map that identifies which language the file is responsible for and all of the built-in messages that will be used for that language.

If you add a language to your project that does not have a language file, that language will use the same messages as the default language.

Getting Additional Language Files

If you need a language file that is not shipped with Setup Factory, please visit the Indigo Rose Web site (www.indigorose.com) and user forums (www.indigorose.com/forums/) where new language files are made available from time to time.

Making Your Own Language File

If after consulting the Indigo Rose web site you still can't find the language file you need, you can always make one yourself. To make a new language file, simply make a copy of the existing language file that you want to translate from, rename it to the new language name, change the language map in the file accordingly and then translate the messages.

To clarify this process, here is an example of how to create a French language file (this is for demonstration purposes only and is unnecessary since French already ships with Setup Factory):

1. Open Windows Explorer to Setup Factory's Languages folder (usually "C:\Program Files\Setup Factory 9\Languages".)

2. Make a copy of English.xml and name it French.xml.

3. Open French.xml in a text editor such as Notepad.

4. Open language_map.xml from the Languages folder in a text editor such as Notepad.

5. Locate the section that maps French in the language_map.xml file. It should look like this:

<Language>
<Name>French</Name>
<Primary>12</Primary>
<Secondary>
<ID>1</ID>
<ID>2</ID>
<ID>3</ID>
<ID>4</ID>
<ID>5</ID>
<ID>6</ID>
</Secondary>
</Language>

6. Copy the above section from language_map.xml and paste it in place of the <Language></Language> section of the French.xml file. This will allow Setup Factory to recognize this file as a language file for the French language.

7. Translate all messages in the <Messages></Messages> section to French. Do not change any actual XML tags. For example:

<MSG_SUCCESS>Success</MSG_SUCCESS>

becomes:

<MSG_SUCCESS>Succès</MSG_SUCCESS>

8. Save the file and re-open Setup Factory. The new language will now be available.

9. Share the file with others!

Adding Languages

To add a new language to your setup, click the Add button in the Language Manager. This will open the Add New Language dialog. Simply select the language that you want to add and click OK. You will then see the language appear in the languages list.

What Happens When You Add a New Language

When you add a new language to your setup, the following happens automatically:

• Setup Factory searches the Languages folder for an appropriate language file for the language. If one is not found, the new language is set to use the default language's language file.

• The newly added language is added to all screens. That is, all screens have messages added to them for the new language. If a translated language file for that particular screen already exists, it will be used. Otherwise, the messages from the default language will be replicated for the new language.

• The newly added language is added to all packages. That is, all packages have names and descriptions added to them for the new language. The default messages for the new language will be replicated from the project's default language.

• The language is added to the list of languages that you can select from in the language selectors throughout the design environment.

Of course, you will still need to go into the Packages and Screens dialogs to verify and/or translate the text for the new language.

Removing Languages

To remove a language from the setup, select the language in the Language Manager's list and click the Remove button. Note that the default language cannot be removed. You will have to make a different language the default language before deleting the original default language.

When you remove a language from the setup, all translations in that language are removed from all screens and packages in your project. Therefore, use caution when removing languages.

The Language Selector

Once a language is added to your setup project, it will be available for translation when editing screens and packages via the language selector. The language selector is simply a combo box that lets you choose the language you will be entering text for in the screen or package.

If you want to work on a language that is not in the list, you will first have to add it through the Language Manager.

Localizing Screens

To localize a screen, open the Screens dialog (Project > Screens) and double-click a screen to open the screen's properties. Next, select the language that you want to enter text for in the language selector. Then, simply type the text that you want for the various fields in the language that you are currently working in.

Note that the Screen ID field on the Attributes tab cannot be translated. The screen ID is a unique identifier for the screen and is never displayed to the end user.

Here is an example of a Welcome screen with English text:

And here is the same screen with French text:

Notice that in the second screenshot, "French" has been selected in the language selector near the bottom of the dialog. The text that you enter always corresponds to the language that is selected in the language selector.

Tip: If the language that you want to translate to doesn't appear in the language selector, you need to add support for that language to your project. This is done by adding the language in the language manager. For more information, see The Language Manager and Adding Languages.

Importing and Exporting Screen Translations

There may be times when you want to have your screens translated by a third party translator. If the translator owns a copy of Setup Factory, you can simply send them your project file, have them translate the screens using the method explained above, and then have them send the project file back to you.

However, it may be that the translator does not own Setup Factory or that you need to work with the project in other ways while the translation is taking place. Setup Factory has a solution for this situation. You must:

1. Open the Screens dialog (Project > Screens).

2. Select the screen that you want to have translated in the Screens list.

3. Click the Advanced button (this will open a popup menu).

4. Select Export Language and then the language that you want to export to.

5. Choose a location to save the file to.

6. Send the exported file to your translator.

7. When you receive the file back, select the screen in the Screens list.

8. Click the Advanced button and then choose Import Language from the popup menu.

9. Locate the translated file and select Open.

10. You will now have the new translated strings in your screen.

Localizing Packages

To localize a package, open the Packages dialog (Project > Packages) and double-click a package to open the package's properties. Next, select the language that you want to enter text for in the language selector. Then, simply type the text that you want for the various fields in the language that you are currently working in.

Note that the Package ID field cannot be translated. The package ID is a unique identifier for the package and is never displayed to the end user.

Here is an example showing the properties of a package that has been localized in English:

And here are the properties of the same package translated into French:

Importing and Exporting Package Translations

Packages can be exported and imported for translation in the same manner that screens are. Please refer to "Importing and Exporting Screen Translations" above for specific instructions on how to do this.

Localizing the Uninstall

The uninstaller uses the same language file that was used by the installer. Setup Factory language files contain all messages needed by the installer and the uninstaller.

The uninstall screens can be translated in the same manner as the installation screens. To work on the uninstall screens, choose Uninstall > Screens from the menu.

Customizing Error Messages and Prompts

If you want to change the default error messages, prompts or status messages used in the setup, you can simply edit the appropriate XML file in the Languages folder using a text editor such as Notepad. Note however that this is not generally recommended; the messages that you change will be propagated to all projects that are built after the changes are made. However, if this is the desired effect, you can certainly do this.

Note also that if you choose to change default messages, the file may be overwritten by a future update to Setup Factory. To avoid this problem, you may want to modify your XML file's name. For example, from english.xml to my_english.xml.

Below is an excerpt from english.xml:

Advanced Techniques

There are a number of advanced techniques that you can use to manipulate the language and the translated language strings in your setup at run time. Most of these methods are accomplished using actions. This section covers a few of these advanced techniques.

Determining the Current Language

There are two actions that can be used to retrieve information about the user's language ID: System.GetDefaultLangID and Application.GetInstallLanguage. Although both actions return a table of information containing language IDs, it is important to know the difference between the two.

System.GetDefaultLangID

System.GetDefaultLangID is used to get the primary and secondary language ID that the user employs in Windows. This is absolute and cannot be changed with any other actions. For example, if this action returns 10 as the primary ID and 13 as the secondary ID you will know that the user's Windows system is configured for Spanish (Chile). There is a complete list of primary and secondary language IDs in the Setup Factory help file.

The information returned by this action can be used in cases where you want to make specific choices about what to do based on the user's absolute system language. For example, if you have a Web site that is translated into several different languages, you might want to make a series of File.OpenURL actions surrounded by if…then statements to jump to the appropriate site:

-- Determine absolute system language
local tblSysLang = System.GetDefaultLangID();

-- Set a default
local strURL = "http://www.yourcompany.com/english");

-- see if we should jump to a different site
if (tblSysLang.Primary == 7) then
strURL = "http://www.yourcompany.com/german");
elseif (tblSysLang.Primary == 10) then
strURL = "http://www.yourcompany.com/spanish");
elseif(tblSysLang.Primary == 16) then
strURL = "http://www.yourcompany.com/italian");
end

-- jump to the Web site
File.OpenURL(strURL);

Application.GetInstallLanguage

Application.GetInstallLanguage is used to retrieve the primary and secondary language ID that is actually being used by the setup. Note that Application.GetInstallLanguage may return a different result than System.GetDefaultLangID if the language being used by the setup differs from the language your user employs in Windows.

For example, let's say that you have three languages in your setup: English (default language), French and German. Suppose a user from Chile runs the setup on their system. Even though their system uses primary ID 10 and secondary ID 13 (which would be returned by System.GetDefaultLangID), Application.GetInstallLanguage will return a primary ID of 9 and a secondary ID of 1 which is the setup's default language (English) since Spanish was not added to the setup at design time.

The value returned by Application.GetInstallLanguage will always be a value for a language that you added to your project using the Language Manager. It will never contain values for languages that were not explicitly included in the setup.

Changing the Current Language

You can change the setup's language at run time at any point using the action Application.SetInstallLanguage. This action will allow you to set the primary and secondary language ID used by the setup. When you call this action, it will actually change all error and status messages as well as the language used by screens and packages "on-the-fly."

One common reason to use this action might be because you want to use a language other than the default if certain other languages cannot be located. Being able to change the language that your setup uses from script allows you can handle certain specific cases in any way you want.

For example, let's say that your setup supports two languages: English (which is the default language) and Simplified Chinese. Since English is the default language, it will be used whenever the setup is run on anything other than Simplified Chinese.

However, you might prefer that the setup use Simplified Chinese if the user runs the setup on a system configured to use Traditional Chinese.

In other words, you want to override the default language rule and force your installer to use Simplified Chinese whenever Traditional Chinese is detected. You can do so easily by placing the following short script in your project's On Startup event:

-- Determine absolute system language
local tblSysLang = System.GetDefaultLangID();
if (tblSysLang.Primary == 4) and (tblSysLang.Secondary == 1) then
-- Traditional Chinese on user's system,
-- so use Simplified instead
Application.SetInstallLanguage(4, 2);
end

Testing Different Languages

You may also want to use the Application.SetInstallLanguage action for testing purposes. For example, if you are running an English version of Windows, you might want to see how your setup will look on an Italian system. Because your system is running in English, the setup will always choose English as the language to display whenever you run it on your system. However, you could force the setup to use Italian by putting the following script in your On Startup event:

Application.SetInstallLanguage(16, 1);

You could even do the above in response to a custom command line option that you handle so that your setup can be forced to use a different language at any time.

Localizing Actions

You may have noticed that there is no language selector when editing scripts in Setup Factory. This means that any text you enter into a script will not be translated for you. However, by using the Application.GetInstallLanguage action you can use if…then statements to do something different based on the language being used.

For example, let's say that your setup supports English and French and you want to show a dialog box using actions that will be localized according to those languages. The following script first determines the language that the setup is using, and then displays one of two possible greetings:

local tblSysLang = Application.GetInstallLanguage();

if (tblSysLang.Primary == 9) then
Dialog.Message("Welcome",
"Welcome to the installer");
end

if (tblSysLang.Primary == 12) then
Dialog.Message("Bienvenue",
"Bienvenue au programme d’installation");
end

Working with Existing Translated Messages

Setup Factory allows you to get and set translated messages for general messages (from the language files), screens, and packages at run time. This is done through several actions.

SetupData.GetLocalizedString

This action allows you to retrieve the localized text for a general message from the language files at run time. The message will be returned in the current install language. For example, the default language files provide messages to confirm if the user wants to abort the setup. Here is a way to show a dialog that confirms if the user wants to abort the setup in the current language:

local strTitle = SetupData.GetLocalizedString("MSG_CONFIRM");
local strPrompt = SetupData.GetLocalizedString("MSG_CONFIRM_ABORT");
local nResult = Dialog.Message( strTitle
, strPrompt
, MB_YESNO
, MB_ICONQUESTION
, MB_DEFBUTTON2 );

if(nResult == IDYES)then
Application.Exit();
end

SetupData.SetLocalizedString

This action allows you to change the value of a localized string at run time. This could be useful if you want to override the default value of an error message at run time so that you don't have to permanently change your language file at design time. For example, let's say that you want to change the message that is displayed if the user tries to cancel the setup. By default it is "The setup is not finished! Do you really want to abort?", but you want to change it to: "Stopping now is not a good idea. Are you sure?"

SetupData.SetLocalizedString("MSG_CONFIRM_ABORT",
"Stopping now is not a good idea. Are you sure?");

Screen.GetLocalizedString and Screen.SetLocalizedString

These actions are used to get and set the localized string for the current language of the currently displayed screen at run time. They work the same way that SetupData.GetLocalizedString and SetupData.SetLocalizedString do except that they will only access strings used on a screen.

SetupData.GetPackageProperties and SetupData.SetPackageProperties

These two actions can be used to get and set the translated string for a package's display name and description at run time. In this case, you will want to work with the table's DisplayName and Description indexes to get and set the text. For example, to display a package named "Documents" display name and description in a dialog box:

local tblPackageProps = SetupData.GetPackageProperties("Documents");

Dialog.Message( tblPackageProps.DisplayName
, tblPackageProps.Description );

Sharing Your Translations

If you do translate a language file or even screens for common use, please feel free to share them in the Indigo Rose forums (www.indigorose.com/forums/). There is a forum in the Setup Factory section where you can find, share and collaborate on translations for setups. You might even be able to trade translation services with other users.


Chapter 8: Security and Expiration

Security and Expiration

Setup Factory comes with installation security options that add another valuable layer of security to your application without sacrificing ease of use. Setup Factory's easy-to-implement security features make unauthorized use prohibitive without creating complications for authorized users.

This chapter will introduce you to the security options available in Setup Factory and get you one step closer to a secure yet easy-to-use installation.

In This Chapter

In this chapter, you'll learn about:

• Security in Setup Factory

• Serial numbers

• Serial number lists

• The Verify Serial Number screen

• Serial number actions

• Date expiration

• Usage count expiration

• Log files, data integrity, and file encryption

• Internet authentication, post-installation security, and other important considerations

Security in Setup Factory

With the ever-increasing threat of software piracy, many developers are choosing to secure not only their software product, but also their installation. This extra layer of security prevents unauthorized users from installing the software and can assist in controlling the distribution of the installer.

In Setup Factory, there are two main ways to secure your installation. The first method involves utilizing product-specific serial numbers. From within Setup Factory, you can create and manage serial number lists. The serial number lists are encrypted once your setup is built. During your installation, you can prompt the user for a serial number using a Verify Serial Number screen or by creating your own custom screen. If the provided serial number is not found on any of your serial number lists, the installation will not continue.

The second method for securing your installation is to set expiration criteria. Your installation can be made to expire (cease to run) under certain situations. For example, your installation could expire after it has been run twice. Or instead, your installation could be made valid for a period of thirty days after which time your customer must procure the most recent version of your software. If the installation has expired, the user is alerted and the installation exits. The alert is fully customizable.

Serial Numbers

Think of a serial number as a pass phrase used by your customers to access the contents of the installation. Each user has a unique pass phrase. During the installation process, the user is prompted for this pass phrase to continue. The serial number provided by the user is then compared to the serial numbers in your list(s). If the serial matches, the installation continues. If the serial does not match, the installation exits.

Serial Number Lists

In Setup Factory, serial numbers in your installation are grouped into 'lists.' A serial number list is an inventory of every valid serial number in your installation.

Setup Factory allows the creation of multiple (separate) serial number lists. One use of multiple lists would be if you wanted to distribute only one setup containing both a standard and enhanced version of your software. In this case, you would create two separate serial number lists, and based on the serial number that your customer provides to the installation, either the standard or enhanced version of your software would be installed. This method of separation is also valid for distributing both a demo and full version of your software in one installation.

Serial Number Lists Are Secure

In Setup Factory, your actual serial number lists are not stored in the installation. Rather, an MD5 hash (or "digest") is calculated for each serial number within each of your lists. These MD5 hashes are then stored in the installer instead of the original values. This ensures that your list of serial numbers is not vulnerable.

When the user enters a serial number, the installer calculates the MD5 hash for that value and then compares it to the list of MD5 hashes that were created from the original serial numbers. If a matching MD5 hash is found, the installer knows that the user's serial number is valid. (Since every MD5 hash is unique, the only way that the MD5 hashes for two serial numbers can match is if the serial numbers are the same.)

This allows the installer to detect a valid serial number without actually knowing what the original serial number was. Since the MD5 hash calculation is irreversible, there is no way for a hacker to retrieve the original serial numbers from the installer. The hacker is reduced to using brute force tactics, i.e. trying a series of serial numbers at random until one works…which, if your serial numbers are sufficiently complex, would be highly prohibitive.

How MD5 Security Works

An MD5 hash is a digital signature that can be used to uniquely identify any piece of data. It is the result of a special calculation that can be applied to any kind of data. This calculation process is strictly one-way. Although you can calculate the MD5 hash for any value, you cannot later retrieve the value from the MD5 hash. It is literally impossible to reverse the process.

This makes MD5 extremely useful for validating serial numbers. Storing the MD5 hash for a serial number allows you to determine whether a matching serial number has been entered without storing any information that could be used to determine what the original serial number was.

Build Configurations

Build configurations are collections of settings that you can switch between when you build the project. They essentially allow you to have different configurations of your software within a single project.

Every serial number list in a Setup Factory project can be associated with one or more build configurations. In other words, you can specify which build configurations a specific serial number list will be included in. This allows you to generate multiple editions of your product from a single project while still allowing you to include different lists of serial numbers in each edition.

For example, let's say you have two build configurations in your project: one for a Professional version, and one for a Standard version of your software. You also have two serial number lists, one for your Professional version, and one for your Standard version. By assigning each serial number list to the appropriate build configuration, you can ensure that each edition has the correct list of serial numbers in it without having to create and maintain two separate projects. You only have to worry about one Setup Factory project file; yet, as you build each separate configuration into its own separate installer, only the corresponding serial number list will be included.

Tip: More information on build configurations can be found in Chapter 11.

Generating Serial Numbers

Once the decision has been made to use serial numbers to secure your installation, a list of serial numbers must be generated. Setup Factory has a built-in tool to generate lists of serial numbers using criteria provided by you.

Serial numbers generated with this tool are created using a serial number "mask" to specify the pattern for all of the serial numbers. In the mask, placeholder characters are used to describe the structure and format of the desired serial numbers. The built-in tool then replaces these placeholder characters with static and random letters or numbers automatically.

This tool is a huge timesaving feature. In mere seconds, you can generate a list of thousands of serial numbers formatted to your specifications.

There are two types of serial number lists that can be generated: random, and sequential. Generally, it is good practice to generate random serial number lists, unless you have a legitimate reason to generate a sequential list.

When considering what format your serial numbers should take, there are a couple of things to keep in mind. First, if you deal with more than one product, you may want to design serial numbers that are product specific (e.g. #####-#####-PRO-##### and #####-#####-STD-#####). Otherwise, if your two separate products generate enough serials, the chance exists that the same number may be generated for both products. As well, differentiating serial numbers according to product type ensures that human beings can differentiate between the numbers.

The second thing to consider is the length of the serial numbers. There is a delicate balance between the security of a serial number and the ease of entering it. A user will not want to enter a hundred-character alphanumeric string. Also, with increased length comes the increased chance the user will mess up a character in the serial number and call your support number unnecessarily.

Importing Serial Numbers

If you already have a list of serial numbers that you wish to use with your installer, you can easily import them into Setup Factory. This is accomplished by choosing Commands > Import on the Serial Number List Properties dialog. Setup Factory can import serial numbers from a text file with one serial number per line.

Alternatively, if your serial numbers are in a spreadsheet program such as Microsoft Excel, it is possible to copy and paste the serials directly into the list.

Exporting Serial Numbers

Once you have serial number lists created, there are many things you can do with them. For example, you could import the lists into a label-printing program to create serial number labels to ship with your product. Or, you could import them into a database to keep track of your customers.

To import your serial number lists into an external program, you first have to export them from Setup Factory. This is accomplished by choosing Commands > Export from the Serial Number List Properties dialog. Setup Factory exports the serial numbers into a text file, with one serial number per line.

As another option, you can copy and paste the serial numbers right from the Serial Number List properties dialog into a spreadsheet program such as Microsoft Excel. exporting serial numbers

The Verify Serial Number Screen

There are two steps required when adding serial number verification to your installation. The first is to create the serial number lists to be included with your installer. The second step is to prompt the user for a serial number during the installation process. This is done by using a Verify Serial Number screen. The Verify Serial Number screen is a ready-made screen template that is included with Setup Factory. It can be added into your project by clicking the Add button on the Before Installing screens dialog.

The Verify Serial Number screen is a modified Edit Field screen with pre-made actions on its On Next event. Right out of the box, this screen will take any serial number provided by the user and compare it to every list in the installation. If you want, the actions can be easily customized to compare the provided serial number to only specific lists in your installation.

Note: You can create your own Verify Serial Number screen; using the ready-to-use solution included with Setup Factory is only one option.

When a new screen is inserted into your installation project, it is inserted at the end of the list of screens. In Setup Factory, the order in which screens appear in the screen list is the order that screens will be displayed in your installation. Since we are treating a serial number screen as a 'locked door' to pass through before the installation can continue, it is good practice to place the serial number screen before any screens that you want only authorized users to see. A typical screen order would be: Welcome screen, License Agreement screen, Verify Serial Number screen, etc.

Serial Number Actions

The same actions that are used by the Verify Serial Number screen to validate the user's serial number can be used to perform the same task elsewhere. You don't even need to use a screen for this purpose; for example, you could use a Dialog.Input action to ask the user for their serial number in a popup dialog box. Or if the user's serial number is stored in a registry key, you could retrieve that value using Registry actions and then use a SetupData.IsValidSerialNumber action to determine whether the serial number is valid for the add-on you’re installing.

The SetupData.IsValidSerialNumber action is incredibly easy to use…you just give it the name of the serial number list you want to search in, and the serial number you want to search for, and it returns 'true' or 'false' according to whether the serial number is valid.

Here's an example that demonstrates how easy it is to validate a serial number:

bValid = SetupData.IsValidSerialNumber("Main", strSerial);
if not bValid then
Dialog.Message("Sorry!", Invalid serial number.");
Application.Exit();
end

In this example, we validate the serial number that was previously stored in a variable named strSerial against a serial number list named "Main." If the serial number is invalid, we display a quick message to the user and then exit the installer.

Date Expiration

One of the expiration criteria available in Setup Factory is date expiration. When this security measure is implemented, your installer functions normally until the expiration date is reached, at which point it will cease to function. If the user runs the installer after the expiration date, they are presented with an error dialog, and the installer exits. (The message presented to the user can be customized.)

Note: Date expiration applies to the installer only and not to the software itself once it has been installed.

As you can see in the image on the next page, there are quite a few options for date expiration. Your installer can be made to expire at a specific date, such as the first of the month, or at the end of the current quarter. Or, it can be set to expire at a relative date, i.e., x days after the installer is built, or x days after the installation is first performed. As well, you have the option of displaying the number of days left to the user, or simply having the installer exit with no prior notice.

Note: The absolute date option, as well as the 'expire x days after build' option, can be used to protect the installer on more than one system. The 'expire x days after first run' option, however, is system specific. If the user runs the installer on one system, and then 50 days later runs it on another system, the installer will still function normally, even if it was set to expire 10 days after first run.

Usage Count Expiration

The second expiration option available to you is usage count expiration. Your installer can be set to expire after x number of uses either on a per-user basis (NT systems only) or on a system-wide basis. This is useful when you want your users to have the most current version of your installer whenever they run the setup, or when you want to allow only one installation on a system, regardless of the number of users.

Note: Usage count expiration can be used by itself, or in combination with date expiration.

Here are some typical usage count expiration settings:

You have the option of limiting the number of uses either by user or by system. As well, you can have the installation abort if the user does not have permission to write to the registry, since the usage information is stored there. Lastly, you can either display the number of uses left to the user, or have the installation expire with no prior warning.

Note: Usage count expiration is system specific. If a user runs an installer that is set to expire after one use, and then copies this installer to another system and runs it there, the installer will function normally on that other system.

In other words, this form of security does not expire the actual installation file; rather, it expires the installation on the current system by writing a value to the Registry. This process does not modify the setup file at all—the setup file will be the same after 100 uses as it was when it was first run.

Log Files

Setup Factory's built-in logging function can quickly become a developer's best friend. It is enabled by default, and contains all the information that you as a developer will need to diagnose a setup gone bad, should that situation arise. Everything that happens during the setup is logged, from which screens were displayed, to what files were installed and where.

Beyond its basic components, the installation log file is fully customizable. You as the developer can choose what information is logged, and what information is not. If you require even more detail than what the built-in logging capabilities provide, you can add custom lines to the log at any point during your installation.

Using log files is invaluable to developers for diagnosing problems. And let's face it, no matter how much testing is done, there will always be one end user who hits a snag. Utilizing log files, you can find out exactly where that snag occurred, and fix the problem. As a result, you save on support costs and keep your customer happy.

Since all this information is (or can be) written to the log file, you may be wondering if log files pose a security risk. In general, no sensitive information is written to the log files by default. Unless you specifically write such information out using actions, the log files should be pretty safe. (Naturally the definition of what could be considered sensitive information may vary from one developer to the next. The best course of action, of course, is to test your installer with log files enabled, and see what kinds of information gets logged—both when the setup completes successfully, and when it encounters errors. If any information that you consider to be sensitive is revealed in the logs, you can adjust the default logging behavior, or turn the logging feature off.) Overall, since so little sensitive information is written to the log files, the risk is typically very low.

Furthermore, nothing is stored in the log file that the user couldn't access using third party setup-monitoring software. In most cases, the usefulness of the log file far outweighs any perceived 'security dangers' that may exist. The log file contains information vital to the diagnosing of installation issues, and by default does not contain any information that is not available to a user by other means, should they desire it. Since you can specify where the log file is created, and can control what information is included in it, there is no reason not to use the logging feature.

Ultimately, the choice of whether or not to use the log file, and how much information should be in that log file, is up to you.

Data Integrity

Whenever using a process that deals with files, whether compression or simply copying, it is important to verify the integrity of the source files. After all, the quality of a copy depends on the quality of the original, and if the original file is 'broken,' it is not possible for the copied file to work.

Setup Factory handles file integrity verification by using CRC32 checksums. At runtime, the setup checks each file as it is installed onto the user's system. If it fails the CRC32 check, an error message is displayed to the user.

Note: CRC values are calculated using an algorithm known as the Cyclic Redundancy Check, or "CRC" for short. Basically, this involves generating a 32-bit number (or "CRC value") from the contents of a file. If the contents of a file change, its CRC value changes as well. This allows the CRC number to be used as a "checksum" in order to identify whether or not the file has changed. It also allows you to distinguish between different versions of a file by comparing its CRC value to the CRC values of the originals.

File Encryption

By default, the files that get stored in Setup Factory's data archive are compressed using a proprietary compression method. Although the proprietary nature of the compression scheme offers some security (e.g. a user can't just extract the files using a third-party tool like WinZip), it is not intended as a security measure.

If you need to fully encrypt any files, you can add Blowfish encryption to your projects using the Crypto actions in Setup Factory.

Note that it is equally (if not more) important to secure your software than it is to secure the installer. If you only secure the installation, all it takes is one user to install the files "legitimately" for the protection to be removed, leaving the door wide open for that user to share the files against your wishes—or for an intruder to steal those files from the user’s unsecured system.

When planning your deployment, it is wise to view the installer as an open vehicle for the files, and to focus on protecting the software after it's installed.

Internet Authentication

A very advanced method of securing an installer is to query a web database using HTTP.Submit actions. For instance, you could use a server-side script (e.g. a PHP script at your web site) to validate the user's serial number by checking it against the list of serial numbers that have already been used. If everything checked out okay, the server-side script would send back a special "key" to unlock the rest of the installation. If the server-side script rejected the user's serial number, the installer would abort the installation.

Note: Traditionally, software installers don't use such elaborate protection methods; usually when such authentication is in place it is implemented in the software itself, in order to continue protecting the software from being shared after the installation. However, this feature of Setup Factory can be used to securely distribute non-executable files, where the distribution itself is the only part that you can secure.

Tip: Setup Factory even has full support for HTTPS transactions. Simply use the HTTP.SubmitSecure and HTTP.DownloadSecure actions which communicate with the server using Secure Sockets Layer (SSL) instead of regular unencrypted HTTP.

Post-Installation Security

Once your software is installed, any security measures taken to protect the setup do not protect the installed software product. Once your software is installed, Setup Factory's job is done. To ensure the security of your software product after installation, you may want to consider a third party security solution. There are many solutions on the market designed to protect your software product beyond the installation stage.

Important Considerations

When planning out product security, it is important to keep in mind that given enough time and resources, even the best security measures can be circumvented. This fact can be illustrated with real-world, billion-dollar security attempts, such as DVD encryption and secure government communications. Given enough time, even these security measures can be 'cracked.'

In addition to securing your installation, and perhaps securing your installed application, you may want to consider controlling the distribution of your installation files. After all, a software thief can't steal something he or she can't find.

Serial numbers can be shared, computer clocks can be set back, and encryption can be broken. The advantage of imposing installation security checks is to make the task of stealing your software more difficult. Making a setup expire, by whatever criteria you choose, is a way to help control your source files. Using serial numbers is a way to track your users, and can be used for such purposes as limiting product support to registered users only.

One final point to keep in mind is that too much security can be a bad thing. While it is important to secure your application to prevent against unauthorized use, it is equally important to allow legitimate users a painless install.


Chapter 9: Dependencies

Dependencies

There are countless software creation tools available to developers today, a number rivaled only by the amount of software dependencies that exist. Whether it's the Visual Basic runtime files, or a complex, proprietary set of database libraries, software created to use various technologies will not function without them, and are thus dependant on these technologies.

Enter Setup Factory's dependency modules. These self-contained wonders of programming science seamlessly integrate with Setup Factory, allowing any developer to ensure that their end users have the required dependencies. If they don't, Setup Factory's dependency modules will make sure the technologies are installed before the setup is allowed to continue.

In This Chapter

In this chapter, you'll learn about:

• Dependencies

• Dependency modules

• Why you should always read the dependency module information

• Detection scripts and installation scripts

• Special early-extracted dependency files

What are Dependencies?

Many applications created with development tools such as Visual Basic require certain technologies to be present on the system in order for the application to run. These technologies are usually files that must be installed alongside the application in order for the application to function. Dependencies range in scope from including small runtime files to requiring the presence of a properly configured local database server. Basically, anything outside of your actual application that your application depends on is a dependency.

Note: Dependencies as they relate to Setup Factory are sometimes referred to as runtime modules.

Dependency Modules

Setup Factory was built with application dependencies in mind, and includes support for dependency detection and installation in the form of dependency modules. Dependency modules are self-contained modules for installing technologies needed by the main application being installed. They consist of a script that detects whether the technology is already installed, and a script (and optional files) that will install the technology if it isn't already installed or needs to be updated. This detection and installation occurs at the beginning of the installation process, before the installation of the main product takes place.

Adding Dependency Modules

Adding a dependency module to your installer is as easy as clicking your left mouse button five times. First, choose Resources > Dependencies (that's 2 clicks). Now, click on Add. Lastly, click the dependency module you want to add, and click OK. You have just added a dependency module to your setup, which will be installed before your actual application files are.

Note: When adding dependency modules you should keep in mind the platform(s) you intend to distribute to (32-bit or 64-bit) and the target operating system(s) (e.g. 64-bit setups will not run on 32-bit operating systems). There may be different versions available that are specific for these targets.

Removing Dependency Modules

Removing a dependency module is even easier than adding one! Instead of five left clicks, this task requires only four. First, choose Resources > Dependencies, as you did to add the module you now wish to remove. Second, click on the dependency module to be eliminated, and click Remove. Yes, it's that easy!

Note: Because Setup Factory's dependency modules are self-contained, they can be added and removed as described. There are no files to worry about, nor actions to create. Simply point, choose, and click.

Adjusting the Order of Dependency Modules

While most dependencies are completely standalone, some dependencies may have dependencies of their own, and will not function unless another dependency is already installed. If this is the case, you will want to adjust the order of the dependency modules within your Setup Factory project to ensure that the modules are installed in the correct order. In other words, if dependency A requires dependency B, you will want to make sure that Setup Factory checks for dependency B first.

Tip: Dependency modules are detected and installed in the order they are listed in on the Dependencies tab of the Resources dialog. You can adjust this order by selecting a dependency module in the list and clicking the Up or Down button to move it up or down.

Getting More Modules

A plethora of dependency modules come with Setup Factory, but if you require a dependency that was not included with Setup Factory, give the More Modules button a try. Clicking the More Modules button will open the Indigo Rose website in your default browser and take you directly to the Setup Factory dependency module page. As more dependency modules are developed, they will be posted there.

Note: It is possible to create your own dependency modules, too. To start a new module, click the Advanced button and choose Create New Module. Name the new module accordingly, and edit its properties to configure the scripts and files that the module will use to detect and install the technology.

Dependency Module Properties

Once you have added a dependency module to your project, you can view and change its settings through the Dependency Module Properties dialog. You can get to this dialog by selecting a module in your project and clicking the Edit button, or by double-clicking on a dependency module within your project.

The Dependency Module Properties dialog has five tabs:

  • Information

  • Detection

  • Installation

  • Files

  • Build

Information

The Information tab contains information about the current dependency module and often contains important instructions that you need to follow in order for the module to function as expected. If there are any related articles and documents that you should review they will be referenced here as well.

Note: Some dependency modules make use of files or settings that you must acquire or configure in order for the module to work. Be sure to read all of the information on this tab whenever you add a dependency module to your project!

Detection

The Detection tab is home to the detection script. This script is written in Lua, and is designed to determine whether the required technology already exists on the user's system. Only if the technology does not exist (or is determined to be an older version that should be updated) will the installation of the dependency continue.

The detection script must include at least one function that will be called by the installer. This detection function will determine what version (if any) of the required technology is installed, and return either true or false: true if the technology is "detected" (i.e. it is already installed and of a sufficient version) and false if the technology is "not detected" (it is either too old or missing altogether).

You can specify which function will be used by typing its name into the edit field at the top of the Detection tab. Some detection scripts may come with multiple versions of a detection function that you can choose from in this way, for instance to perform the detection using alternate methods.

Tip: You can have more than one function in the detection script. This is useful if, for example, you wanted to run different scripts based on a certain condition, such as the user’s operating system. In this case, you would create one function that is called by the installer, which would then decide which specific dependency function to run.

The value that the detection function returns is what determines whether the dependency module's installation script is performed. The installation script will only be performed if the detection function returns false, indicating that the required technology was not detected. If the function returns true, the installer will proceed to the next dependency module in the list and run its dependency script.

Detection Happens Early

The detection script is run at the beginning of the installation, before the actual installation of your product takes place. At this stage of the installation, the only files that are available to the installer are the files that already exist on the user's system, any external files that were distributed alongside the setup, and any files that were included as primer files (which get extracted at the very beginning of the installation). None of the files that are in the Archive file list are available yet, since they are still packed inside the setup archive waiting to be installed.

When modifying or creating a detection script, it’s important to remember what files will be available at that stage of the installation.

Installation

The Installation tab contains the script that will be executed if (and only if) the detection function returns false—in other words, if the detection script determines that the required technology is not installed on the user's system.

If the detection script is the brains of the operation, the installation script is the brawn. Once given the green light by the detection script, the installation script charges ahead, performing all the tasks that are required in order to get the missing technology installed on the user's system.

Often this will consist of simply launching another self-packaged installer that will handle the installation of the dependency files. Of course, you can also use any of Setup Factory's built-in actions to perform whatever tasks you choose.

Like the detection script, when the dependency module's installation script runs, it runs at the beginning of the installation, before the actual installation of your product takes place…long before any of the files in the Archive file list are installed. For this reason, most dependency modules are designed to include their own "dependency files" that will be extracted before the installation script is run. These dependency files are listed on the Files tab of the Dependency Module Properties dialog.

Files

The Files tab contains a list of files that are required by the installation script. These files will be extracted if (and only if) the detection script determines that the required technology is not installed. This essentially allows the dependency module to bring its own files along for installation script to use.

The files listed on the Files tab typically consist of a setup executable that will install the required technology and any additional files needed by the installation script.

Note: If the detection script determines that the technology is already installed on the user's system, the files listed on the Files tab will not be extracted.

Files on the Files tab are extracted to the user's temp folder in a uniquely named subfolder. This is a subfolder within the installer's own unique folder in the user's temp folder. (Each installer creates a uniquely-named subfolder in the user's temp folder if it needs a place to extract temporary files. This is done to avoid overwriting existing files that the user may have stored in the temp folder, or that might have been left behind by a previous installation.)

For example, if the unique run-time folder name was vb6sp6, the path that the files would be extracted to would be something similar to:

%TempFolder%\\_ir_sf_temp_0\\vb6sp6

Constants in Dependency File Paths

The paths in the list of dependency files often contain constants like #SUFDIR#. #SUFDIR# is a built-in constant that gets replaced at build time with the path to the Setup Factory program folder on your development system—i.e., where the Setup Factory design environment is running from. This allows the built-in dependency modules to reference files that are located in the Setup Factory application folder, without knowing the exact location that you chose to install Setup Factory to.

Build

The Build tab contains the build configurations you want the dependency module to be a part of. You can check or uncheck the boxes in the build configurations tree to include or exclude it from the distribution. For further information about build configurations, see Chapter 11: Building and Distributing.

Note: When adding dependency modules you should keep in mind the platform(s) you intend to distribute to (32-bit or 64-bit) and the target operating system(s) (e.g. 64-bit setups will not run on 32-bit operating systems). There may be different versions available that are specific for these targets. Build configurations may assist in some of these cases.


Chapter 10: Uninstall

Uninstall

Uninstallation: an inevitability that, though sad, is a fact of life. With Setup Factory, the task of removing your labor of love from a user's system is easy to configure, and in many cases, works with little to no involvement on your part.

Yet if you are performing many advanced tasks, the uninstallation is entirely customizable, from what screens are displayed, to what actions are performed, and when.

In This Chapter

In this chapter, you'll learn about:

• What happens during an uninstallation

• What uninstallation tasks you need to implement yourself

• Configuring the uninstaller

• The uninstall configuration file

• Control panel options, uninstall shortcuts, and uninstall log files

• Customizing the uninstall interface

• Uninstall actions and events

What is an Uninstaller?

The uninstaller is the Ying to the installer's Yang. Everything created, installed, or otherwise modified by the installer is undone by the uninstaller. The best uninstaller leaves no trace of the original software product on the user's system and is easy to use.

Most programs list their uninstallers in the "Add or Remove Programs" control panel applet, which you access by choosing Start > Control Panel > Add or Remove Programs. Each item in Add or Remove Programs represents an already-installed program that can be uninstalled. (Some programs also provide a shortcut to their uninstaller in the same place where their program shortcuts are found on the Start menu.)

By default, Setup Factory includes an uninstaller with every installation built. This default uninstaller is accessed through the Add or Remove Programs dialog.

What Happens During an Uninstallation

In a nutshell, during an uninstallation everything that was done automatically by the installer is undone. Files from your main file list are removed, shortcuts created by the installer are deleted, and folders that were automatically created during the installation are destroyed.

Note: The uninstaller does NOT remove files created or copied using actions, nor does it remove shortcuts, folders, or registry entries created via actions. By default the uninstaller only removes what the installer created automatically. Anything done with actions in the installation will need to be undone with actions in the uninstallation.

Tip: You can use UninstallData actions to add items to the list of files, folders, shortcuts, and registry entries that will be removed by the uninstaller.

By default, every file in your project is removed from the user's system by the uninstaller. However, you can bypass this on a file-by-file basis by adjusting either the shared file or never remove options in the file's properties. Any file for which the never remove option has been enabled will not be removed by the uninstaller.

If a file is specified as a shared file, then in addition to installing it, a usage count is set for the file. For example, if you have two separate products that share a DLL, when the user installs the second product, the usage count for that DLL is increased by one. When one of the products is removed, the usage count is decreased by one. The file is only removed from the system if it has a usage count of zero, which indicates that no other currently installed program needs it.

Going Beyond the Default Behavior

Unless you have made system changes using actions, the default behavior of the uninstaller should be sufficient. However, if you have made any changes to the user's system using actions, those changes must be reversed using actions during the uninstall.

For example, if you created a bunch of registry keys using Registry actions and made a couple of shortcuts using the Shell.CreateShortcut action, then you have to reverse these changes by using their counterpart actions (for example, Registry.DeleteKey and Shell.DeleteShortcut) in the uninstaller.

Of course, the uninstaller doesn't have to be limited to simply undoing things that were done by the installer. You can make it do anything you want; for example, you could present the user with an option to extend their license at a discount, or submit a message to an authentication system on your web site that will allow that user to install the software somewhere else.

One of the great things about Setup Factory is how customizable it is. Installations can be created for almost any need. The same is true for uninstallations created with Setup Factory. The uninstallation user interface, combined with actions, can be customized to handle any situation.

Configuring the Uninstall

By default, Setup Factory creates an uninstaller for your project that handles the basics automatically. Any files that are installed (without using actions) are marked to be uninstalled automatically, and there is a standard uninstall interface already set up.

If you need more functionality than Setup Factory's default features provide, then you can fully customize your uninstaller. The uninstaller is in essence a project within your actual project; it has its own startup and shutdown actions and its own screens, complete with all expected events.

The Uninstall Configuration File

Setup Factory utilizes an XML configuration file to keep track of the changes that the installer makes to the user's system during the installation, such as what files were installed and what shortcuts were created. This configuration file is dynamically created by the installer as it proceeds through the installation.

Tip: Although the uninstall configuration file is created during the installation, it can be altered manually at any time during the installation or uninstallation by using UninstallData actions.

The uninstall configuration file contains the following information:

• Path to the uninstall data file

• Paths of all files that were installed

• Session variables and values

• All shortcuts created

• Any folders created by the installation

• Any additional scripts that should run during the uninstallation

Note: The uninstall configuration file does not contain any information about tasks completed with actions. Any files, shortcuts, folders, session variables, etc. created with or modified by actions are not referenced in the uninstall configuration file unless you specifically add them to the file using UninstallData actions.

The uninstall configuration file is basically a list of steps for the uninstaller to follow in order to perform the uninstallation.

Note: The uninstall configuration file is different from the uninstall data file. The uninstall data file is an encrypted binary file containing all of your design time settings—screens, actions, etc.—and cannot be changed outside of the Setup Factory design environment.

Uninstall Settings

The Uninstall Settings dialog can be accessed by choosing Uninstall > Settings from the menu. Typical uninstall settings can be seen here:

The Create Uninstall Option

The Create uninstall option basically toggles the uninstall functionality. When this option is checked, your installer will create an uninstaller at runtime. When it is unchecked, no uninstaller will be created.

File Names and Locations

The File Names and Locations section of the Uninstall Settings dialog allows you to specify: the folder where the uninstall data and configuration files will be stored, the name that should be used for the uninstall configuration file, and where to store the uninstaller's executable.

Overwrite Options

The If Uninstall Already Exists section of the Uninstall Settings dialog allows you to control how your installer behaves when it finds existing uninstall settings on the user's system from a previous installation. For example, you can choose whether to overwrite the control panel entry with the new uninstall settings, or to leave the existing control panel entry alone.

Other Options

The Allow silent uninstall option controls whether the uninstaller can be run in 'silent mode' (with no interface showing) using a command line option.

The Always on top option makes the uninstall window always appear on top of all other windows on the desktop. The window will remain on top even if the user switches to another application.

Uninstall Background

The Show background window option makes your uninstaller run with a window in the background (covering the desktop). The settings for this background window are the same as the background window settings for your installer.

Control Panel Options

Setup Factory creates uninstalls that are extremely easy to use. One user friendly aspect is a control panel entry—specifically an entry in the Add or Remove Programs dialog—which makes uninstallation a breeze. The settings for this entry are found by choosing Uninstall > Control Panel, which opens the Uninstall Settings dialog directly to the Control Panel tab.

The first setting that you can configure on the Control Panel tab is whether or not to list the uninstall in the Add or Remove Programs dialog. Unchecking this option will prevent your installer from making this entry.

Assuming, however, that you choose to make this entry, the next settings to configure are the Entry Settings. This is where you can specify the description, Registry key, and icon to use for the control panel entry.

After the Entry Settings are configured, only the Support Info settings remain. The information you place here will be available from the Add or Remove Programs dialog and is often used to help the user identify your product.

Tip: For more information on any of these settings, see the program reference.

Typical control panel options:

A typical control panel entry:

Shortcut Icons

An alternative to creating an entry in the Add or Remove Programs dialog is to include an uninstall shortcut in the start menu. This option is found on the Shortcut tab of the Uninstall Settings dialog, and can be accessed from the design environment by choosing Uninstall > Shortcut. If enabled, this option will create an uninstall shortcut in the start menu alongside the other shortcuts created by your installation.

Typical shortcut options:

Log Files

In the event that your uninstallation fails, having a log file available to diagnose the problem is often extremely helpful. Knowing exactly where and why your uninstall failed are two very valuable pieces of information. Setup Factory enables uninstallation logging by default.

You can configure the uninstall log file options or turn off this option entirely from the Logs tab of the Uninstall Settings dialog. You can access this dialog from the design environment by choosing Uninstall > Log Files.

The settings on the Logs tab allow you to configure where the log file is stored, how the data is written, and what data is written to the log file.

Note: Do not disable this feature unless you are absolutely positive that you will never need the log file. Regardless of how much testing you do, there is always a chance that your installer will produce unforeseen behavior on some user's system. The task of diagnosing such problems is made exponentially easier with a log file. If there is a security concern, keep in mind that you can set the log file to include no action details, and then use your own actions to output only the information you deem appropriate.

The Uninstall Interface

The uninstall user interface can be configured similarly to how the installer was configured. By default, the uninstaller will use the theme settings from the installer, but these can be overridden on a screen-by-screen basis if you desire.

You can control the look and feel of your uninstaller just as you created your installer by adding, removing and manipulating the screens to be included. The uninstaller uses its own screens, independent of the screens included in the installer. By manipulating the various properties of each respective screen, you can have an uninstaller that reflects the look and feel of the original installer, or you can create an entirely new appearance.

Tip: For more information on configuring screens, please see Chapter 3.

Uninstall Actions

Using Setup Factory, you can quickly and easily create an installer to suit most general requirements. However the real power of Setup Factory lies in the ability to use the free-form scripting engine, combined with a plethora of built-in actions, to perform whatever task you desire.

It is important to keep in mind that whatever tasks you perform using actions during your installation will not automatically be undone by the uninstaller. You must manually make use of the uninstall actions to undo whatever changes the installation actions made to the user's system.

With the above in mind, it is possible to automate some of the uninstallation tasks by making use of the UninstallData actions. These are a group of actions that allow you to interact with the uninstall configuration file directly, during both the installation and uninstallation. So instead of adding actions to the uninstall to reverse what your actions did during the installation, you can use UninstallData actions to modify the uninstall configuration file, and let the uninstaller take care of undoing the changes for you.

One advantage of this is that it allows you to put your "undo" actions in the installer, instead of in the uninstaller. This lets you keep the actions that undo your changes near the actions that made the changes in the first place, making it much less likely that you'll forget to update the uninstall actions whenever the install actions change.

Tip: For more information on actions and how to work with them, see Chapter 4. The command reference is also an excellent resource for learning about actions and the action wizard.

Uninstall Events

As with the installer, there are five uninstall project events: On Startup, On Pre Uninstall, On Uninstall Error, On Post Uninstall, and On Shutdown. These events are accessible by choosing Actions from the Uninstall menu.

It is up to you to decide where to place your actions based on the task that the actions are performing.

The On Startup event is the first event that is triggered in a Setup Factory uninstallation. This event is one of the first things that occurs and is your first chance to make anything happen in your uninstallation.

The On Startup event occurs before any screens are displayed. This makes it a good place to perform pre-uninstallation tasks, such as making sure the end user is positive that they want to uninstall.

The On Pre Uninstall event is triggered just before the uninstallation enters the uninstall phase and begins uninstalling files from the end user's computer. This event is fired right after the last screen in the Before Uninstalling screen stage is displayed.

The On Uninstall Error event is triggered when an error occurs during the setup's uninstall, allowing you to handle it in a custom way. If you would like to ignore the error that just occurred, you can call the Application.IgnoreLastError action on this event to ignore the last error that occurred.

The On Post Uninstall event is triggered after the uninstall phase of the uninstallation has completed, right before the first screen of the After Uninstalling screen stage is displayed.

The On Shutdown event is the last event that will be triggered in your uninstallation. It occurs after all screens in your uninstallation have been displayed and is your last chance to accomplish anything in your uninstallation. This is an excellent stage to complete any cleanup tasks, such as deleting temp files that you may have created earlier, or directing the user to your website.


Chapter 11: Building and Distributing

Building and Distributing

Designing your installation is only half the battle. Once you have something tangible to work with, you must build and eventually distribute your installer. Luckily, Setup Factory makes this process as seamless as the actual installer design process.

From choosing your distribution media to fully unattended build options, Setup Factory makes building your project a pleasure, not a chore.

In This Chapter

In this chapter, you'll learn about:

• The build process

• The publish wizard

• Build configurations

• Constants

• Pre- and post-build steps

• Build-related preferences

• Testing and distributing your installer

The Build Process

Once you have finished creating your Setup Factory project, you must build it into the actual setup file (or files, if you're building a multi-part installer). This is similar to a programmer compiling code once the code is complete.

When you choose to build your project, Setup Factory will first verify all files and folders that you have included. It will then convert any serial number lists you have into MD5 hash lists and encrypt them. It collects any fonts you have opted to install and converts any graphics into the setup file. Once the images have been converted, the language modules are processed, all the contained files are compressed, the configuration file is created, and the compressed setup is built.

The Publish Wizard

With the goal of making the build process as seamless as possible, Setup Factory includes a Publish Wizard to assist you.

The first screen of the Publish Wizard allows you to specify which type of media you will be distributing your installation on. By identifying this, you are essentially telling Setup Factory what the maximum size of any one created file should be. For example, if your setup is 1.15 gigs and you are distributing on 700mb CDs, Setup Factory will split your installation into two files, ready to be burned.

Note: If your setup project contains more than one build configuration, the wizard will prompt you to choose which build configuration you want to use before it starts:

The second screen of the Publish Wizard prompts you for the location that you would like to publish to, as well as the name of the file that you would like to create.

Once the Next button is clicked on the above screen, Setup Factory begins to build the setup.

Tip: You can configure Setup Factory to hide the output process during the build to decrease the build time. You can do this by disabling the "Report status during build" preference found in the Build section of Edit > Preferences.

Once the build process is complete, the following summary screen is displayed. This screen presents a summary of the build process and displays any errors. Once you are finished viewing this screen, you can simply click Finish. If the Open output folder option is checked, the output folder will be opened automatically when you click Finish.

Tip: If you need more information or want to trace an error, you can view the entire build log file by clicking the Build Log button.

Build Settings

The Build Settings dialog, accessible by choosing Settings from the Publish menu, allows you to set the defaults you would like to use for the build process. Basically, any setting affecting the final built file is found here.

When working with an installer that can be built into one file, changing the setup filename simply changes the name of the built file. However, when working with an installer that will be split into two or more segments, changing the setup filename also changes the names of each of the segment files.

The segment size setting allows you to specify the maximum file size that any installation file will have. If your complete setup is larger than the size specified, the final installation will be split into two or more files. This is especially useful if you are distributing your installation on fixed-size media such as CDs or DVDs.

Tip: Setup Factory has pre-specified segment sizes to make distributing your installations on standard media such as 650mb and 700mb CDs, DVDs a breeze.

The compression settings provide some flexibility in how much, and the type of compression that is used when generating your setup. These settings can be used to control the size of the generated file, speed of the build process, as well as runtime decompression performance.

The platform setting controls the desired platform of your generated setup. Setup Factory can generate either 32-bit or 64-bit setups which makes it possible to distribute both 32-bit and 64-bit compiled applications/files.

Note: If your setup includes dependency modules, plugins, or any other resources, you must also ensure you have selected the correct platform version of those resources.

Tip: If you plan to distribute both 32-bit and 64-bit setup files for your application, it may be possible to create a single setup project for both platforms instead of separate project files. For minor differences between platform distributions, it may be beneficial to create build configurations containing the differing settings for each platform in order to maintain a single setup project file.

To start, create a build configuration containing all the settings required for one of the platforms, making note of any settings not controlled directly by build configurations that may need to be different. Such settings may require the creation of build constants in order for the information to be dynamically set at build time.

Once you've defined all of the settings for your first configuration, you can add a new one by copying all of the settings from your initial one and then modify it accordingly. Build configurations are discussed in the next section.

Build Configurations

One of the many timesaving features of Setup Factory is the ability to use build configurations within your setup project. When working with two similar installs, such as a Standard and Professional version of your software product, it is often easier to create one setup project and have only the required files and serial number lists for each respective installer included at build time. Or, you may have an application you are distributing on both 32-bit and 64-bit platforms where the differences in settings are minimal (see the Platform setting on the Setup File tab of Build Settings).

Build configurations can be added to the current project by clicking the Add button ( [image] ) near the top of the Build Settings dialog. Once a build configuration is added, you can assign files, folders, and serial numbers to it from the main design window.

Files and folders can be associated with specific build configurations from their respective properties dialog, or they can be associated with 'All' build configurations. Serial numbers can be included as well with only specific build configurations by assigning the list to a build configuration in the Serial Numbers List Properties dialog. Other areas that are part of build configurations include Dependencies, Primer Files, Script Files and Plugins, all of which are available under the Resources menu item.

Constants

Constants are essentially design time variables. They are similar to session variables, but instead of being expanded as the user runs the installer, they are expanded when you build the project. In other words, when you build your project, all of the constants are automatically replaced by the values assigned to them.

You can define constants on the Constants tab of the Build Settings dialog, which you can access by choosing Publish > Settings.

Clicking the Add button displays a dialog where you can name the constant and give it a value.

By default, each constant has a name that begins and ends with a # sign (but they don't have to), and an associated value. The name will be replaced by this value throughout the project when the project is built. It's exactly like a big search-and-replace operation that happens whenever you build the project.

Since each constant is essentially just a name that gets replaced with different text, you can use them just about anywhere. You can use them on screens, in file paths, in actions…pretty much anywhere that you can enter text.

Note: If constants are used in script, they must be in a different format, such as _DEBUG_ to eliminate any syntax errors.

Build Configurations

The values that you assign to constants are specific to each build configuration. In fact, this is what makes constants so useful. By assigning different values to the constants in each build configuration, you can make sweeping changes to your project by simply selecting a different build configuration when you build it.

Note: The build configuration determines which values are used when the project is built.

Here are some things you can do with constants and build configurations:

• use constants in the paths for your source files, and use different versions of the files for different build configurations

• use constants for the name of the product, so you can switch between building a full version and an evaluation version just by changing the build configuration

• use actions that test the value of a constant named #DEBUG#, and set it to true in a "Debug" build configuration and false in all other configurations. Then you can leave helpful debugging code in your scripts, and only have it performed when you build the Debug configuration. For example:

function MyFunc()
nCount = nCount + 1;
if _DEBUG_ then
Debug.ShowWindow();
Debug.Print("Inside MyFunc()
 - nCount = " .. nCount);
end
end

Unattended Builds

Constants are extremely useful for performing unattended builds because they can be changed using a command line argument. You can even use constants to specify the output location, and which build configuration to use. The possibilities are endless.

For example, you could create a batch file that would generate a unique installer for every one of your customers, with the customer's name showing up on one or all of the screens during the installation.

For more information on performing unattended builds of your project, search for "Unattended Build Options" in the program reference.

Pre/Post Build Steps

There may be instances where you want to run a program either before or after your installer is built. Setup Factory makes this process easy through Pre and Post Build Steps. On the Pre/Post Build tab of the Build Settings dialog, you can set a program to Run Before Build, and a program to Run After Build.

The uses of this feature are limited only by your imagination. You could, for example, chain several product build processes together, or execute a preliminary batch step. The possibilities are limitless.

You can specify the path to the desired program in either of the Run Program fields. Any command line arguments that are needed should be specified in the Command Line arguments fields. If you want Setup Factory to 'sleep' while the other program is open, check the Wait for program to finish running checkbox.

Preferences

To control how Setup Factory handles the build process, you can modify the Build Preferences by choosing Preferences from the Edit menu. You can control whether Setup Factory opens the output folder by default, disable the publish wizard, disable the output status and, when not using the wizard, control whether a confirmation dialog is displayed before the build process begins.

Typical build preferences can be seen here:

Testing Your Installer

One of the most important and often overlooked steps when creating an installer is testing it after it has been built. You should test your installer on as many computers, operating systems, and platforms as possible. Try it on every operating system and platform that your software product supports. Windows XP, Windows Vista, Windows 7, Windows 8, Windows 8.1 and Windows 10 all have both slight and major differences between them, and should be thoroughly tested. As well, test your installer on various OS configurations with different resolutions, color depth and font sizes, and on systems with a lot of hard-drive space and on those with a very limited amount of hard drive space.

If you have made use of Setup Factory's multilingual support, be sure to test out each language in your install. If you included any dependency modules, test your installer on a virgin system to ensure that the dependency files install correctly.

Many problems with installers have simple causes, such as forgetting to include a file, or moving a file to an incorrect location. Compatibility issues can crop up when your software is not written for a particular operating system, or when the dependency files that are included in the installer do not function on a particular operating system.

If you do run into a problem with your installer, test it on as many systems as possible to narrow down the problem. You might discover a common factor between the systems that is causing the installer (or your software) to fail.

It is very important to test before you distribute. An 'internal build' of your installer is much easier to recall should a crippling problem arise than a public release is.

Tip: For information related to tracking down script-related issues, see Debugging Your Scripts in the Scripting Guide.

Distributing Your Installer

Once you have thoroughly tested your installer, it is time to distribute your software. After all, a beautifully created setup is an awful waste if your customers and clients cannot enjoy it! There are several ways to distribute your software, but the three main media are CD-ROMs, DVDs, and the Internet. Setup Factory allows you to specify a segment size to effectively split your installer into smaller sized files. This is ideal for distributing an installer that is larger than the target media.

Preparing your installer for distribution is as easy as selecting your desired media type in the publish wizard, and publishing to a hard drive folder. Once the build operation has completed, simply copy each segment file (or just the setup executable if there is only one file) onto separate discs, and you are ready to go! Or, if you have opted to distribute via the Internet, simply take the generated setup file and upload it onto your website for your customers to download.


Scripting Guide

Contents

Welcome to the online version of the Setup Factory Scripting Guide.

Introduction

A Quick Example of Scripting in Setup Factory

Important Scripting Concepts

Script is Global

Script is Case-Sensitive

Comments

Delimiting Statements

Variables

What are Variables?

Variable Scope

Local Variables

Variable Naming

Reserved Keywords

Types and Values

Number

String

Nil

Boolean

Function

Table

Variable Assignment

Expressions and Operators

Arithmetic Operators

Relational Operators

Logical Operators

Concatenation

Operator Precedence

Control Structures

If

While

Repeat

For

Tables (Arrays)

Creating Tables

Accessing Table Elements

Numeric Arrays

Associative Arrays

Using For to Enumerate Tables

Copying Tables

Table Functions

Functions

Function Arguments

Returning Values

Returning Multiple Values

Redefining Functions

Putting Functions in Tables

String Manipulation

Concatenating Strings

Comparing Strings

Counting Characters

Finding Strings

Replacing Strings

Extracting Strings

Converting Numeric Strings into Numbers

Other Built-in Functions

Script Functions

dofile

require

type

Actions

Debugging Your Scripts

Error Handling

Syntax Errors

Functional Errors

Debug Actions

Application.GetLastError

Debug.ShowWindow

Debug.Print

Debug.SetTraceMode

Debug.GetEventContext

Dialog.Message

Final Thoughts

Other Resources

Help File

User’s Guide

Indigo Rose Web Site

Indigo Rose Technical Support

The Lua Web Site


Introduction

One of the powerful features of Setup Factory is its scripting engine. This document will introduce you to the new scripting environment and language.

Setup Factory scripting is very simple, with only a handful of concepts to learn. Here is what it looks like:

a = 5;
if a < 10 then
Dialog.Message("Guess what?", "a is less than 10");
end

(Note: this script is only a demonstration. Don’t worry if you don’t understand it yet.)

The example above assigns a value to a variable, tests the contents of that variable, and if the value turns out to be less than 10, uses a Setup Factory action called “Dialog.Message” to display a message to the user.

New programmers and experienced coders alike will find that Setup Factory is a powerful, flexible yet simple scripting environment to work in.

A Quick Example of Scripting in Setup Factory

Here is a short tutorial showing you how to enter a script into Setup Factory and preview the results:

1. Start a new project.

2. In your project's On Startup event, type in the following text:
Dialog.Message("Title", "Hello World");

It should look like this when you’re done:

6. Click OK to close the action editor.

7. Choose Publish > Build from the menu.

8. Once your project has finished building, run the created file (typically setup.exe).

The On Startup event is triggered as soon as the installation is loaded, and the script you entered will be performed. You should see the following dialog appear:

Congratulations! You have just made your first script. Though this is a simple example, it shows you just how easy it is to make something happen in your Setup Factory Application. You can use the above method to try out any script you want in Setup Factory .


Important Scripting Concepts

There are a few important things that you should know about the Setup Factory scripting language in general before we go on.

Script is Global

The scripting engine is global to the runtime environment. That means that all of your events will “know” about other variables and functions declared elsewhere in the product. For example, if you assign “myvar = 10;” in the project’s On Startup event, myvar will still equal 10 when the next event is triggered. There are ways around this global nature (see Variable Scope), but it is generally true of the scripting engine.

Script is Case-Sensitive

The scripting engine is case-sensitive. This means that upper and lower case characters are important for things like keywords, variable names and function names.

For example:

ABC = 10;
aBC = 7;

In the above script, ABC and aBC refer to two different variables, and can hold different values. The lowercase “a” in “aBC” makes it completely different from “ABC” as far as Setup Factory is concerned.

The same principle applies to function names as well. For example:

Dialog.Message("Hi", "Hello World");

...refers to a built-in Setup Factory function. However,

DIALOG.Message("Hi", "Hello World");

...will not be recognized as the built-in function, because DIALOG and Dialog are seen as two completely different names.

Note: It’s entirely possible to have two functions with the same spelling but different capitalization—for example, GreetUser and gREeTUSeR would be seen as two totally different functions. Although it’s definitely possible for such functions to coexist, it’s generally better to give functions completely different names to avoid any confusion.

Comments

You can insert non-executable comments into your scripts to explain and document your code. In a script, any text after two dashes (--) on a line will be ignored. For example:

-- Assign 10 to variable abc
abc = 10;

...or:

abc = 10; -- Assign 10 to abc

Both of the above examples do the exact same thing—the comments do not affect the script in any way.

You can also create multi-line comments by using --[[ and ]]-- on either side of the comment:

--[[ This is
a multi-line
comment ]]--
a = 10;

You should use comments to explain your scripts as much as possible in order to make them easier to understand by yourself and others.

Delimiting Statements

Each unique statement can either be on its own line and/or separated by a semi-colon (;). For example, all of the following scripts are valid:

Script 1:

a = 10
MyVar = a

Script 2:

a = 10; MyVar = a;

Script 3:

a = 10;
MyVar = a;

However, we recommend that you end all statements with a semi-colon (as in scripts 2 and 3 above).


Variables

What are Variables?

Variables are very important to scripting in Setup Factory. Variables are simply “nicknames” or “placeholders” for values that might need to be modified or re-used in the future. For example, the following script assigns the value 10 to a variable called “amount.”

amount = 10;

Note: We say that values are “assigned to” or “stored in” variables. If you picture a variable as a container that can hold a value, assigning a value to a variable is like “placing” that value into a container. You can change this value at any time by assigning a different value to the variable; the new value simply replaces the old one. This ability to hold changeable information is what makes variables so useful.

Here are a couple of examples demonstrating how you can operate on the “amount” variable:

amount = 10;
amount = amount + 20;
Dialog.Message("Value", amount);

This stores 10 in the variable named amount, then adds 20 to that value, and then finally makes a message box appear with the current value (which is now the number 30) in it.

You can also assign one variable to another:

a = 10;
b = a;
Dialog.Message("Value", b);

This will make a message box appear with the number 10 in it. The line “b = a;” assigns the value of “a” (which is 10) to “b.”

Variable Scope

As mentioned earlier in this document, all variables in Setup Factory are global by default. This just means that they exist project-wide, and hold their values from one script to the next. In other words, if a value is assigned to a variable in one script, the variable will still hold that value when the next script is executed.

For example, if you enter the script:

foo = 10;

...into screen’s On Preload event, and then enter:

Dialog.Message("The value is:", foo);

...into the screen’s On Next event, the second script will use the value that was assigned to “foo” in the first script. As a result, when the Next button is clicked, a message box will appear with the number 10 in it.

Note: The order of execution is important...in order for one script to be able to use the value that was assigned to the variable in another script, that other script has to be executed first. In the above example, the screen’s On Preload event is triggered before the screen’s On Next event, so the value 10 is already assigned to foo when the On Next event’s script is executed.

Local Variables

The global nature of the scripting engine means that a variable will retain its value throughout your entire project. You can, however, make variables that are non-global, by using the special keyword “local.” Putting the word “local” in front of a variable assignment creates a variable that is local to the current script or function.

For example, let’s say you have the following three scripts in the same project:

Script 1:

-- assign 10 to x
x = 10;

Script 2:

local x = 500;
Dialog.Message("Local value of x is:", x);
x = 250; -- this changes the local x, not the global one
Dialog.Message("Local value of x is:", x);

Script 3:

-- display the global value of x
Dialog.Message("Global value of x is:", x);

Let’s assume these three scripts are performed one after the other. The first script gives x the value 10. Since all variables are global by default, x will have this value inside all other scripts, too. The second script makes a local assignment to x, giving it the value of 500—but only inside that script. If anything else inside that script wants to access the value of x, it will see the local value instead of the global one. It’s like the “x” variable has been temporarily replaced by another variable that looks just like it, but has a different value.

(This reminds me of those caper movies, where the bank robbers put a picture in front of the security cameras so the guards won’t see that the vault is being emptied. Only in this case, it’s like the bank robbers create a whole new working vault, just like the original, and then dismantle it when they leave.)

When told to display the contents of x, the first Dialog.Message action inside script #2 will display 500, since that is the local value of x when the action is performed. The next line assigns 250 to the local value of x—note that once you make a local variable, it completely replaces the global variable for the rest of the script.

Finally, the third script displays the global value of x, which is still 10.

Variable Naming

Variable names can be made up of any combination of letters, digits and underscores as long as they do not begin with a number and do not conflict with reserved keywords.

Examples of valid variables names:

a
strName
_My_Variable
data1
data_1_23
index
bReset
nCount

Examples of invalid variable names:

1
1data
%MyValue%
$strData
for
local
_FirstName+LastName_
User Name

Reserved Keywords

The following words are reserved and cannot be used for variable or function names:

and break do else elseif
end false for function if
in local nil not or
repeat return table then true
until while

Types and Values

Setup Factory’s scripting language is dynamically typed. There are no type definitions—instead, each value carries its own type.

What this means is that you don’t have to declare a variable to be of a certain type before using it. For example, in C++, if you want to use a number, you have to first declare the variable’s type and then assign a value to it:

int j;
j = 10;

The above C++ example declares j as an integer, and then assigns 10 to it.

As we have seen, in Setup Factory you can just assign a value to a variable without declaring its type. Variables don’t really have types; instead, it’s the values inside them that are considered to be one type or another. For example:

j = 10;

...this automatically creates the variable named “j” and assigns the value 10 to it. Although this value has a type (it’s a number), the variable itself is still typeless. This means that you can turn around and assign a different type of value to j, like so:

j = "Hello";

This replaces the number 10 that is stored in j with the string “Hello.” The fact that a string is a different type of value doesn’t matter; the variable j doesn’t care what kind of value it holds, it just stores whatever you put in it.

There are six basic data types in Setup Factory: number, string, nil, boolean, function, and table. The sections below will explain each data type in more detail.

Number

A number is exactly that: a numeric value. The number type represents real numbers—specifically, double-precision floating-point values. There is no distinction between integers and floating-point numbers (also known as “fractions”)...all of them are just “numbers.” Here are some examples of valid numbers:

4 4. .4 0.4 4.57e-3 0.3e12

String

A string is simply a sequence of characters. For example, “Joe2” is a string of four characters, starting with a capital “J” and ending with the number “2.” Strings can vary widely in length; a string can contain a single letter, or a single word, or the contents of an entire book.

Strings may contain spaces and even more exotic characters, such as carriage returns and line feeds. In fact, strings may contain any combination of valid 8-bit ASCII characters, including null characters (“\0”). Setup Factory automatically manages string memory, so you never have to worry about allocating or de-allocating memory for strings.

Strings can be used quite intuitively and naturally. They should be delimited by matching single quotes or double quotes. Here are some examples that use strings:

Name = "Joe Blow";
Dialog.Message("Title", "Hello, how are you?");
LastName = 'Blow';

Normally double quotes are used for strings, but single quotes can be useful if you have a string that contains double quotes. Whichever type of quotes you use, you can include the other kind inside the string without escaping it. For example:

doubles = "How's that again?";
singles = 'She said "Talk to the hand," and I was all like "Dude!"';

If we used double quotes for the second line, it would look like this:

escaped = "She said \"Talk to the hand,\" and I was all like \"Dude!\"";

Normally, the scripting engine sees double quotes as marking the beginning or end of a string. In order to include double quotes inside a double-quoted string, you need to escape them with backslashes. This tells the scripting engine that you want to include an actual quote character in the string.

The backslash and quote (\") is known as an escape sequence. An escape sequence is a special sequence of characters that gets converted or “translated” into something else by the script engine. Escape sequences allow you to include things that can’t be typed directly into a string.

The escape sequences that you can use include:

\a - bell
\b - backspace
\f - form feed
\n - newline
\r - carriage return
\t - horizontal tab
\v - vertical tab
\\ - backslash
\" - quotation mark
\' - apostrophe
\[ - left square bracket
\] - right square bracket

So, for example, if you want to represent three lines of text in a single string, you would use the following:

Lines = "Line one.\nLine two.\nLine three";
Dialog.Message("Here is the String", Lines);

This assigns a string to a variable named Lines, and uses the newline escape sequence to start a new line after each sentence. The Dialog.Message function displays the contents of the Lines variable in a message box, like this:

Another common example is when you want to represent a path to a file such as
C:\My Folder\My Data.txt. You just need to remember to escape the backslashes:

MyPath = "C:\\My Folder\\My Data.txt";

Each double-backslash represents a single backslash when used inside a string.

If you know your ASCII table, you can use a backslash character followed by a number with up to three digits to represent any character by its ASCII value. For example, the ASCII value for a newline character is 10, so the following two lines do the exact same thing:

Lines = "Line one.\nLine two.\nLine three";
Lines = "Line one.\10Line two.\10Line three";

However, you will not need to use this format very often, if ever.

You can also define strings on multiple lines by using double square brackets ([[ and ]]). A string between double square brackets does not need any escape characters. The double square brackets lets you type special characters like backslashes, quotes and newlines right into the string. For example:

Lines = [[Line one.
Line two.
Line three.]];

is equivalent to:

Lines = "Line one.\nLine two.\nLine three";

This can be useful if you have preformatted text that you want to use as a string, and you don’t want to have to convert all of the special characters into escape sequences.

The last important thing to know about strings is that the script engine provides automatic conversion between numbers and strings at run time. Whenever a numeric operation is applied to a string, the engine tries to convert the string to a number for the operation. Of course, this will only be successful if the string contains something that can be interpreted as a number.

For example, the following lines are both valid:

a = "10" + 1; -- Result is 11
b = "33" * 2; -- Result is 66

However, the following lines would not give you the same conversion result:

a = "10+1"; -- Result is the string "10+1"
b = "hello" + 1; -- ERROR, can’t convert "hello" to a number

For more information on working with strings, see the topic String Manipulation.

Nil

Nil is a special value type. It basically represents the absence of any other kind of value.

You can assign nil to a variable, just like any other value. Note that this isn’t the same as assigning the letters “nil” to a variable, as in a string. Like other keywords, nil must be left unquoted in order to be recognized. It should also be entered in all lowercase letters.

Nil will always evaluate to false when used in a condition:

a = nil;
if a then
-- Any lines in here
-- will not be executed
end

It can also be used to “delete” a variable:

y = "Joe Blow";
y = nil;

In the example above, “y” will no longer contain a value after the second line.

Boolean

Boolean variable types can have one of two values: true, or false. They can be used in conditions and to perform Boolean logic operations. For example:

boolybooly = true;
if boolybooly then
-- Any script in here will be executed
end

This sets a variable named boolybooly to true, and then uses it in an if statement. Similarly:

a = true;
b = false;
if (a and b) then
-- Any script here will not be executed because
-- true and false is false.
end

This time, the if statement needs both “a” and “b” to be true in order for the lines inside it to be executed. In this case, that won’t happen because “b” has been set to false.

Function

The script engine allows you to define your own functions (or “sub-routines”), which are essentially small pieces of script that can be executed on demand. Each function has a name which is used to identify the function. You can actually use that function name as a special kind of value, in order to store a “reference” to that function in a variable, or to pass it to another function. This kind of reference is of the function type.

For more information on functions, see the topic Functions.

Table

Tables are a very powerful way to store lists of indexed values under one name. Tables are actually associative arrays—that is, they are arrays which can be indexed not only with numbers, but with any kind of value (including strings).

Here are a few quick examples (we cover tables in more detail in the topic Tables(Arrays):

Example 1:

guys = {"Mark", "Lorne", "Darryl"};
Dialog.Message("Second Name in the List", guys[2]);

This will display a message box with the word “Lorne” in it.

Example 2:

t = {};
t.FirstName = "Michael";
t.LastName = "Jackson";
t.Occupation = "Singer";
Dialog.Message(t.FirstName, t.Occupation);

This will display the following message box:

You can assign tables to other variables as well. For example:

table_one = {};
table_one.FirstName = "Michael";
table_one.LastName = "Jackson";
table_one.Occupation = "Singer";
table_two = table_one;
occupation = table_two.Occupation;
Dialog.Message(table_one.FirstName, occupation);

Tables can be indexed using array notation (my_table[1]), or by dot notation if not indexed by numbers (my_table.LastName).

Note that when you assign one table to another, as in the following line:

table_two = table_one;

...this doesn’t actually copy table_two into table_one. Instead, table_two and table_one both refer to the same table.

This is because the name of a table actually refers to an address in memory where the data within the table is stored. So when you assign the contents of the variable table_one to the variable table_two, you’re copying the address, and not the actual data. You’re essentially making the two variables “point” to the same table of data.

In order to copy the contents of a table, you need to create a new table and then copy all of the data over one item at a time.

For more information on copying tables, see the topic Tables.

Variable Assignment

Variables can have new values assigned to them by using the assignment operator (=). This includes copying the value of one variable into another. For example:

a = 10;
b = "I am happy";
c = b;

It is interesting to note that the script engine supports multiple assignment:

a, b = 1, 2;

After the script above, the variable “a” contains the number 1 and the variable “b” contains the number 2.

Tables and functions are a bit of a special case: when you use the assignment operator on a table or function, you create an alias that points to the same table or function as the variable being “copied.” Programmers call this copying by reference as opposed to copying by value.


Expressions and Operators

An expression is anything that evaluates to a value. This can include a single value such as “6” or a compound value built with operators such as “1 + 3”. You can use parentheses to “group” expressions and control the order in which they are evaluated. For example, the following lines will all evaluate to the same value:

a = 10;
a = (5 * 1) * 2;
a = 100 / 10;
a = 100 / (2 * 5);

Arithmetic Operators

Arithmetic operators are used to perform mathematical operations on numbers. The following mathematical operators are supported:

+ (addition)
- (subtraction)
* (multiplication)
/ (division)
% (modulo)
^ (exponentiation)
unary - (negation)

Here are some examples:

a = 5 + 2;
b = a * 100;
twentythreepercent = 23 / 100;
neg = -29;
pos = -neg;

Relational Operators

Relational operators allow you to compare how one value relates to another. The following relational operators are supported:

> (greater-than)
< (less-than)
<= (less-than or equal to)
>= (greater than or equal to)
~= (not equal to)
== (equal)

All of the relational operators can be applied to any two numbers or any two strings. All other values can only use the == operator to see if they are equal.

Relational operators return Boolean values (true or false). For example:

10 > 20; -- resolves to false

a = 10;
a > 300; -- false

(3 * 200) > 500; -- true
"Brett" ~= "Lorne" -- true

One important point to mention is that the == and ~= operators test for complete equality, which means that any string comparisons done with those operators are case sensitive. For example:

"Jojoba" == "Jojoba"; -- true
"Wildcat" == "wildcat"; -- false
"I like it a lot" == "I like it a LOT"; -- false

"happy" ~= "HaPPy"; -- true

Logical Operators

Logical operators are used to perform Boolean operations on Boolean values. The following logical operators are supported:

and (only true if both values are true)
or (true if either value is true)
not (returns the opposite of the value)

For example:

a = true;
b = false;
c = a and b; -- false
d = a and nil; -- false
e = not b; -- true

Note that only nil and false are considered to be false, and all other values are true.

For example:

iaminvisible = nil;
if iaminvisible then
-- any lines in here won't happen
-- because iaminvisible is considered false
Dialog.Message("You can't see me!", "I am invisible!!!!");
end

if "Brett" then
-- any lines in here WILL happen, because only nil and false
-- are considered false...anything else, including strings,
-- is considered true
Dialog.Message("What about strings?", "Strings are true.");
end

Concatenation

In Setup Factory scripting, the concatenation operator is two periods (..). It is used to combine two or more strings together. You don’t have to put spaces before and after the periods, but you can if you want to.

For example:

name = "Joe".." Blow"; -- assigns "Joe Blow" to name
b = name .. " is number " .. 1; -- assigns "Joe Blow is number 1" to b

Operator Precedence

Operators are said to have precedence, which is a way of describing the rules that determine which operations in a series of expressions get performed first. A simple example would be the expression 1 + 2 * 3. The multiply (*) operator has higher precedence than the add (+) operator, so this expression is equivalent to 1 + (2 * 3). In other words, the expression 2 * 3 is performed first, and then 1 + 6 is performed, resulting in the final value 7.

You can override the natural order of precedence by using parentheses. For instance, the expression (1 + 2) * 3 resolves to 9. The parentheses make the whole sub-expression “1 + 2” the left value of the multiply (*) operator. Essentially, the sub-expression 1 + 2 is evaluated first, and the result is then used in the expression 3 * 3.

Operator precedence follows the following order, from lowest to highest priority:

and or
<     >   <=   >=   ~=   ==
..
+ -
* / %
not # - (unary)
^

Operators are also said to have associativity, which is a way of describing which expressions are performed first when the operators have equal precedence. In the script engine, all binary operators are left associative, which means that whenever two operators have the same precedence, the operation on the left is performed first. The exception is the exponentiation operator (^), which is right-associative.

When in doubt, you can always use explicit parentheses to control precedence. For example:

a + 1 < b/2 + 1

...is the same as:

(a + 1) < ((b/2) + 1)

...and you can use parentheses to change the order of the calculations, too:

a + 1 < b/(2 + 1)

In this last example, instead of 1 being added to half of b, b is divided by 3.


Control Structures

The scripting engine supports the following control structures: if, while, repeat and for.

If

An if statement evaluates its condition and then only executes the “then” part if the condition is true. An if statement is terminated by the “end” keyword. The basic syntax is:

if condition then
do something here
end

For example:

x = 50;
if x > 10 then
Dialog.Message("result", "x is greater than 10");
end

y = 3;
if ((35 * y) < 100) then
Dialog.Message("", "y times 35 is less than 100");
end

In the above script, only the first dialog message would be shown, because the second if condition isn't true...35 times 3 is 105, and 105 is not less than 100.

You can also use else and elseif to add more “branches” to the if statement:

x = 5;
if x > 10 then
Dialog.Message("", "x is greater than 10");
else
Dialog.Message("", "x is less than or equal to 10");
end

In the preceding example, the second dialog message would be shown, because 5 is not greater than 10.

x = 5;
if x == 10 then
Dialog.Message("", "x is exactly 10");
elseif x == 11 then
Dialog.Message("", "x is exactly 11");
elseif x == 12 then
Dialog.Message("", "x is exactly 12");
else
Dialog.Message("", "x is not 10, 11 or 12");
end

In that example, the last dialog message would be shown, because x is not equal to 10, or 11, or 12.

While

The while statement is used to execute the same "block" of script over and over until a condition is met. Like if statements, while statements are terminated with the “end” keyword. The basic syntax is:

while condition do
do something here
end

The condition must be true in order for the actions inside the while statement (the “do something here” part above) to be performed. The while statement will continue to loop as long as this condition is true. Here's how it works:

If the condition is true, all of the actions between the “while” and the corresponding “end” will be performed. When the “end” is reached, the condition will be reevaluated, and if it's still true, the actions between the “while” and the “end” will be performed again. The actions will continue to loop like this until the condition evaluates to false.

For example:

a = 1;
while a < 10 do
a = a + 1;
end

In the preceding example, the “a = a + 1;” line would be performed 9 times.

You can break out of a while loop at any time using the “break” keyword. For example:

count = 1;
while count < 100 do
count = count + 1;
if count == 50 then
break;
end
end

Although the while statement is willing to count from 1 to 99, the if statement would cause this loop to terminate as soon as count reached 50.

Repeat

The repeat statement is similar to the while statement, except that the condition is checked at the end of the structure instead of at the beginning. The basic syntax is:

repeat
do something here
until condition

For example:

i = 1;
repeat
i = i + 1;
until i > 10

This is similar to one of the while loops above, but this time, the loop is performed 10 times. The “i = i + 1;” part gets executed before the condition determines that a is now larger than 10.

You can break out of a repeat loop at any time using the “break” keyword. For example:

count = 1;
repeat
count = count + 1;
if count == 50 then
break;
end
until count > 100

Once again, this would exit from the loop as soon as count was equal to 50.

For

The for statement is used to repeat a block of script a specific number of times. The basic syntax is:

for variable = start,end,step do
do something here
end

The variable can be named anything you want. It is used to “count” the number of trips through the for loop. It begins at the start value you specify, and then changes by the amount in step after each trip through the loop. In other words, the step gets added to the value in the variable after the lines between the for and end are performed. If the result is smaller than or equal to the end value, the loop continues from the beginning.

For example:

-- This loop counts from 1 to 10:
for x = 1, 10 do
Dialog.Message("Number", x);
end

The above example displays 10 dialog messages in a row, counting from 1 to 10.
Note that the step is optional—if you don’t provide a value for the step, it defaults to 1.

Here’s an example that uses a step of “-1” to make the for loop count backwards:

-- This loop counts from 10 down to 1:
for x = 10, 1, -1 do
Dialog.Message("Number", x);
end

That example would display 10 dialog messages in a row, counting back from 10 and going all the way down to 1.

You can break out of a for loop at any time using the “break” keyword. For example:

for i = 1, 100 do
if count == 50 then
break;
end
end

Once again, this would exit from the loop as soon as count was equal to 50.

There is also a variation on the for loop that operates on tables. For more information on that, see Using For to Enumerate Tables.


Tables (Arrays)

Tables are very useful. They can be used to store any type of value, including functions or even other tables.

Creating Tables

There are generally two ways to create a table from scratch. The first way uses curly braces to specify a list of values:

my_table = {"apple","orange","peach"};

associative_table = {fruit="apple", vegetable="carrot"}

The second way is to create a blank table and then add the values one at a time:

my_table = {};
my_table[1] = "apple";
my_table[2] = "orange";
my_table[3] = "peach";

associative_table = {};
associative_table.fruit = "apple";
associative_table.vegetable = "carrot";

Accessing Table Elements

Each “record” of information stored in a table is known as an element. Each element consists of a key, which serves as the index into the table, and a value that is associated with that key.

There are generally two ways to access an element: you can use array notation, or dot notation. Array notation is typically used with numeric arrays, which are simply tables where all of the keys are numbers. Dot notation is typically used with associative arrays, which are tables where the keys are strings.

Here is an example of array notation:

t = { "one", "two", "three"};
Dialog.Message("Element one contains:", t[1]);

Here is an example of dot notation:

t = { first="one", second="two", third="three"};
Dialog.Message("Element 'first' contains:", t.first);

Numeric Arrays

One of the most common uses of tables is as arrays. An array is a collection of values that are indexed by numeric keys. In the scripting engine, numeric arrays are one-based. That is, they start at index 1.

Here are some examples using numeric arrays:

Example 1:

myArray = {255,0,255};
Dialog.Message("First Number", myArray[1]);

This would display a dialog message containing the number “255.”

Example 2:

alphabet = {"a","b","c","d","e","f","g","h","i","j","k",
"l","m","n","o","p","q","r","s","t","u","v","w","x","y","z"};
Dialog.Message("Seventh Letter", alphabet[7]);

This would display a dialog message containing the letter “g.”

Example 3:

myArray = {};
myArray[1] = "Option One";
myArray[2] = "Option Two";
myArray[3] = "Option Three";

This is exactly the same as the following:

myArray = {"Option One", "Option Two", "Option Three"};

Associative Arrays

Associative arrays are the same as numerical arrays except that the indexes can be numbers, strings or even functions.

Here is an example of an associative array that uses a last name as an index and a first name as the value:

arrNames = {Anderson="Jason",
Clemens="Roger",
Contreras="Jose",
Hammond="Chris",
Hitchcock="Alfred"};

Dialog.Message("Anderson's First Name", arrNames.Anderson);

The resulting dialog message would look like this:

Here is an example of a simple employee database that keeps track of employee names and birth dates indexed by employee numbers:

Employees = {}; -- Construct an empty table for the employee numbers

-- store each employee's information in its own table
Employee1 = {Name="Jason Anderson", Birthday="07/02/82"};
Employee2 = {Name="Roger Clemens", Birthday="12/25/79"};

-- store each employee's information table
-- at the appropriate number in the Employees table
Employees[100099] = Employee1;
Employees[137637] = Employee2;

-- now typing "Employees[100099]" is the same as typing "Employee1"
Dialog.Message("Birthday",Employees[100099].Birthday);

The resulting dialog message would look like this:

Using For to Enumerate Tables

There is a special version of the for statement that allows you to quickly and easily enumerate the contents of an array. The syntax is:

for index,value in pairs (table) do
operate on index and value
end

For example:

mytable = {"One","Two","Three"};

-- display a message for every table item
for j,k in pairs(mytable) do
Dialog.Message("Table Item", j .. "=" .. k);
end

The result would be three dialog messages in a row, one for each of the elements in mytable, like so:

Remember the above for statement, because it is a quick and easy way to inspect the values in a table. If you just want the indexes of a table, you can leave out the value part of the for statement:

a = {One=1,Two=2,Three=3};

for k in pairs(a) do
Dialog.Message("Table Index",k);
end

The above script will display three message boxes in a row, with the text “One,” “Three,” and then “Two.”

Whoa there—why aren’t the table elements in order? The reason for this is that internally the scripting engine doesn’t store tables as arrays, but in a super-efficient structure known as a hash table. (Don’t worry, I get confused about hash tables too.) The important thing to know is that when you define table elements, they are not necessarily stored in the order that you define or add them, unless you use a numeric array (i.e. a table indexed with numbers from 1 to whatever).

Copying Tables

Copying tables is a bit different from copying other types of values. Unlike variables, you can't just use the assignment operator to copy the contents of one table into another. This is because the name of a table actually refers to an address in memory where the data within the table is stored. If you try to copy one table to another using the assignment operator, you end up copying the address, and not the actual data.

For example, if you wanted to copy a table, and then modify the copy, you might try something like this:

table_one = { mood="Happy", temperature="Warm"
 };

-- create a copy
table_two = table_one;

-- modify the copy
table_two.temperature = "Cold";

Dialog.Message("Table one temperature is:", table_one.temperature);
Dialog.Message("Table two temperature is:", table_two.temperature);

If you ran this script, you would see the following two dialogs:

Wait a minute...changing the “temperature” element in table_two also changed it in table_one. Why would they both change?

The answer is simply because the two are in fact the same table.

Internally, the name of a table just refers to a memory location. When table_one is created, a portion of memory is set aside to hold its contents. The location (or “address”) of this memory is what gets assigned to the variable named table_one.

Assigning table_one to table_two just copies that memory address—not the actual memory itself.

It’s like writing down the address of a library on a piece of paper, and then handing that paper to your friend. You aren’t handing the entire library over, shelves of books and all...only the location where it can be found.

If you wanted to actually copy the library, you would have to create a new building, photocopy each book individually, and then store the photocopies in the new location.

That’s pretty much how it is with tables, too. In order to create a full copy of a table, contents and all, you need to create a new table and then copy over all of the elements, one element at a time.

Luckily, the for statement makes this really easy to do. For example, here’s a modified version of our earlier example, that creates a “true” copy of table_one.

table_one = { mood="Happy", temperature="Warm"
 };

-- create a copy
table_two = {};
for index, value in pairs(table_one) do
table_two[index] = value;
end

-- modify the copy
table_two.temperature = "Cold";

Dialog.Message("Table one temperature is:", table_one.temperature);
Dialog.Message("Table two temperature is:", table_two.temperature);

This time, the dialogs show that modifying table_two doesn’t affect table_one at all:

Table Functions

There are a number of built-in table functions at your disposal, which you can use to do such things as inserting elements into a table, removing elements from a table, and counting the number of elements in a table. For more information on these table functions, please see Program Reference / Actions / Table in the online help.


Functions

By far the coolest and most powerful feature of the scripting engine is functions. You have already seen a lot of functions used throughout this document, such as “Dialog.Message.” Functions are simply portions of script that you can define, name and then call from anywhere else.

Although there are a lot of built-in Setup Factory functions, you can also make your own custom functions to suit your specific needs. In general, functions are defined as follows:

function function_name (arguments)
function script here
return return_value;
end

The first part is the keyword “function.” This tells the scripting engine that what follows is a function definition. The function_name is simply a unique name for your function. The arguments are parameters (or values) that will be passed to the function every time it is called. A function can receive any number of arguments from 0 to infinity (well, not infinity, but don’t get technical on me). The “return” keyword tells the function to return one or more values back to the script that called it.

The easiest way to learn about functions is to look at some examples. In this first example, we will make a simple function that shows a message box. It does not take any arguments and does not return anything.

function HelloWorld()
Dialog.Message("Welcome","Hello World");
end

Notice that if you put the above script into an event and preview your installation, nothing happens. Well, that is true and not true. It is true that nothing visible happens but the magic is in what you don’t see. When the event is fired and the function script is executed, the function called “HelloWorld” becomes part of the scripting engine. That means it is now available to the rest of the installation in any other script.

This brings up an important point about scripting in Setup Factory . When making a function, the function does not get “into” the engine until the script is executed. That means that if you define HelloWorld() in a button’s On Click event, but that event never gets triggered (because the user doesn’t click on the button), the HelloWorld() function will never exist. That is, you will not be able to call it from anywhere else.
That is why, in general, it is best to define your global functions in the global script of the project. (To access the global script, choose Resources > Global Functions from the menu.)

Now back to the good stuff. Let’s add a line to actually call the function:

function HelloWorld()
Dialog.Message("Welcome","Hello World");
end

HelloWorld();

The “HelloWorld();” line tells the scripting engine to “go perform the function named HelloWorld.” When that line gets executed, you would see a welcome message with the text “Hello World” in it.

Function Arguments

Let’s take this a bit further and tell the message box which text to display by adding an argument to the function.

function HelloWorld(Message)
Dialog.Message("Welcome", Message);
end

HelloWorld("This is an argument");

Now the message box shows the text that was “passed” to the function.

In the function definition, “Message” is a variable that will automatically receive whatever argument is passed to the function. In the function call, we pass the string “This is an argument” as the first (and only) argument for the HelloWorld function.

Here is an example of using multiple arguments.

function HelloWorld(Title, Message)
Dialog.Message(Title, Message);
end

HelloWorld("This is argument one", "This is argument two");
HelloWorld("Welcome", "Hi there");

This time, the function definition uses two variables, one for each of its two arguments...and each function call passes two strings to the HelloWorld function.

Note that by changing the content of those strings, you can send different arguments to the function, and achieve different results.

Returning Values

The next step is to make the function return values back to the calling script. Here is a function that accepts a number as its single argument, and then returns a string containing all of the numbers from one to that number.

function Count(n)

-- start out with a blank return string
ReturnString = "";

for num = 1,n do
-- add the current number (num) to the end of the return string
ReturnString = ReturnString..num;

-- if this isn't the last number, then add a comma and a space
-- to separate the numbers a bit in the return string
if (num ~= n) then
ReturnString = ReturnString..", ";
end
end

-- return the string that we built
return ReturnString;
end

CountString = Count(10);
Dialog.Message("Count", CountString);

The last two lines of the above script uses the Count function to build a string counting from 1 to 10, stores it in a variable named CountString, and then displays the contents of that variable in a dialog message box.

Returning Multiple Values

You can return multiple values from functions as well:

function SortNumbers(Number1, Number2)
if Number1 <= Number2 then
return Number1, Number2
else
return Number2, Number1
end
end

firstNum, secondNum = SortNumbers(102, 100);
Dialog.Message("Sorted", firstNum ..", ".. secondNum);

The above script creates a function called SortNumbers that takes two arguments and then returns two values. The first value returned is the smaller number, and the second value returned is the larger one. Note that we specified two variables to receive the return values from the function call on the second last line. The last line of the script displays the two numbers in the order they were sorted into by the function.

Redefining Functions

Another interesting thing about functions is that you can override a previous function definition simply by re-defining it.

function HelloWorld()
Dialog.Message("Message","Hello World");
end

function HelloWorld()
Dialog.Message("Message","Hello Earth");
end

HelloWorld();

The script above shows a message box that says “Hello Earth,” and not “Hello World.” That is because the second version of the HelloWorld() function overrides the first one.

Putting Functions in Tables

One really powerful thing about tables is that they can be used to hold functions as well as other values. This is significant because it allows you to make sure that your functions have unique names and are logically grouped. (This is how all of the Setup Factory functions are implemented.) Here is an example:

-- Make the functions:
function HelloEarth()
Dialog.Message("Message","Hello Earth");
end

function HelloMoon()
Dialog.Message("Message","Hello Moon");
end

-- Define an empty table:
Hello = {};

-- Assign the functions to the table:
Hello.Earth = HelloEarth;
Hello.Moon = HelloMoon;

-- Now call the functions:
Hello.Earth();
Hello.Moon();

It is also interesting to note that you can define functions right in your table definition:

Hello = {
Earth = function () Dialog.Message("Message","Hello Earth") end,
Moon = function () Dialog.Message("Message","Hello Moon") end };

-- Now call the functions:
Hello.Earth();
Hello.Moon();


String Manipulation

In this section we will briefly cover some of the most common string manipulation techniques, such as string concatenation and comparisons.

(For more information on the string functions available to you in Setup Factory , see Program Reference / Actions / String in the online help.)

Concatenating Strings

We have already covered string concatenation, but it is well worth repeating. The string concatenation operator is two periods in a row (..). For example:

FullName = "Bo".." Derek"; -- FullName is now "Bo Derek"

-- You can also concatenate numbers into strings
DaysInYear = 365;
YearString = "There are "..DaysInYear.." days in a year.";

Note that you can put spaces on either side of the dots, or on one side, or not put any spaces at all. For example, the following four lines will accomplish the same thing:

foo = "Hello " .. user_name;
foo = "Hello ".. user_name;
foo = "Hello " ..user_name;
foo = "Hello "..user_name;

Comparing Strings

Next to concatenation, one of the most common things you will want to do with strings is compare one string to another. Depending on what constitutes a “match,” this can either be very simple, or just a bit tricky.

If you want to perform a case-sensitive comparison, then all you have to do is use the equals operator (==). For example:

strOne = "Strongbad";
strTwo = "Strongbad";

if strOne == strTwo then
Dialog.Message("Guess what?", "The two strings are equal!");
else
Dialog.Message("Hmmm", "The two strings are different.");
end

Since the == operator performs a case-sensitive comparison when applied to strings, the above script will display a message box proclaiming that the two strings are equal.

If you want to perform a case-insensitive comparison, then you need to take advantage of either the String.Upper or String.Lower function, to ensure that both strings have the same case before you compare them. The String.Upper function returns an all-uppercase version of the string it is given, and the String.Lower function returns an all-lowercase version. Note that it doesn’t matter which function you use in your comparison, so long as you use the same function on both sides of the == operator in your if statement.

For example:

strOne = "Mooohahahaha";
strTwo = "MOOohaHAHAha";

if String.Upper(strOne) == String.Upper(strTwo) then
Dialog.Message("Guess what?", "The two strings are equal!");
else
Dialog.Message("Hmmm", "The two strings are different.");
end

In the example above, the String.Upper function converts strOne to “MOOOHAHAHAHA” and strTwo to “MOOOHAHAHAHA” and then the if statement compares the results. (Note: the two original strings remain unchanged.) That way, it doesn’t matter what case the original strings had; all that matters is whether the letters are the same.

Counting Characters

If you ever want to know how long a string is, you can easily count the number of characters it contains. Just use the String.Length function, like so:

twister = "If a wood chuck could
 chuck wood, how much would...um...";
num_chars = String.Length(twister);
Dialog.Message("That tongue twister has:", num_chars .. "
 characters!");

...which would produce the following dialog message:

Finding Strings

Another common thing you’ll want to do with strings is to search for one string within another. This is very simple to do using the String.Find action.

For example:

strSearchIn = "Isn't it a wonderful day outside?";
strSearchFor = "wonder";

-- search for strSearchFor inside strSearchIn
nFoundPos = String.Find(strSearchIn, strSearchFor);

if nFoundPos ~= nil then
-- found it!
Dialog.Message("Search Result", strSearchFor ..
" found at position " .. nFoundPos);
else
-- no luck
Dialog.Message("Search Result", strSearchFor .. " not found!");
end

...would cause the following message to be displayed:

Tip: Try experimenting with different values for strSearchFor and strSearchIn.

Replacing Strings

One of the most powerful things you can do with strings is to perform a search and replace operation on them. The following example shows how you can use the String.Replace action to replace every occurrence of a string with another inside a target string.

strTarget = "There can be only one.
 Only one is allowed!";
strSearchFor = "one";
strReplaceWith = "a dozen";
strNewString = String.Replace(strTarget, strSearchFor, strReplaceWith);
Dialog.Message("After searching and replacing:", strNewString);

-- create a copy of the target string with no spaces in it
strNoSpaces = String.Replace(strTarget, " ", "");
Dialog.Message("After removing spaces:", strNoSpaces);

The above example would display the following two messages:

Extracting Strings

There are three string functions that allow you to “extract” a portion of a string, rather than copying the entire string itself. These functions are String.Left, String.Right, and String.Mid.

String.Left copies a number of characters from the beginning of the string. String.Right does the same, but counting from the right end of the string instead. String.Mid allows you to copy a number of characters starting from any position in the string.

You can use these functions to perform all kinds of advanced operations on strings.

Here’s a basic example showing how they work:

strOriginal = "It really is good to see you again.";

-- copy the first 13 characters into strLeft
strLeft = String.Left(strOriginal, 13);

-- copy the last 18 characters into strRight
strRight = String.Right(strOriginal, 18);

-- create a new string with the two pieces
strNeo = String.Left .. "awesome" .. strRight .. " Whoa.";

-- copy the word "good" into strMiddle
strMiddle = String.Mid(strOriginal, 13, 4);

Converting Numeric Strings into Numbers

There may be times when you have a numeric string, and you need to convert it to a number.

For example, if you have an input field where the user can enter their age, and you read in the text that they typed, you might get a value like “31”. Because they typed it in, though, this value is actually a string consisting of the characters “3” and “1”.

If you tried to compare this value to a number, you would get a syntax error saying that you attempted to compare a number with a string.

For example, the following script:

age = "31";
if age > 18 then
Dialog.Message("", "You're older than 18.");
end

...would produce the following error message:

The problem in this case is the line that compares the contents of the variable “age” with the number 18:

if age > 18 then

This generates an error because age contains a string, and not a number. The script engine doesn’t allow you to compare numbers with strings in this way. It has no way of knowing whether you wanted to treat age as a number, or treat 18 as a string.

The solution is simply to convert the value of age to a number before comparing it. There are two ways to do this. One way is to use the String.ToNumber function.

The String.ToNumber function translates a numeric string into the equivalent number, so it can be used in a numeric comparison.

age = "31";
if String.ToNumber(age) > 18 then
Dialog.Message("", "You're older than 18.");
end

The other way takes advantage of the scripting engine’s ability to convert numbers into strings when it knows what your intentions are. For example, if you’re performing an arithmetic operation (such as adding two numbers), the engine will automatically convert any numeric strings to numbers for you:

age = "26" + 5; -- result is a numeric value

The above example would not generate any errors, because the scripting engine understands that the only way the statement makes sense is if you meant to use the numeric string as a number. As a result, the engine automatically converts the numeric string to a number so it can perform the calculation.

Knowing this, we can convert a numeric string to a number without changing its value by simply adding 0 to it, like so:

age = "31";
if (age + 0) > 18 then
Dialog.Message("", "You're older than 18.");
end

In the preceding example, adding zero to the variable gets the engine to convert the value to a number, and the result is then compared with 18. No more error.


Other Built-in Functions

Script Functions

There are three other built-in functions that may prove useful to you: dofile, require, and type.

dofile

Loads and executes a script file. The contents of the file will be executed as though it was typed directly into the script. The syntax is:

dofile(file_path);

For example, say we typed the following script into a file called MyScript.lua (just a text file containing this script, created with notepad or some other text editor):

Dialog.Message("Hello", "World");

Now we include the file as a primer file in our installation.

Now, wherever we add the following line of script to an event:

dofile(SessionVar.Expand("%TempLaunchFolder%\\MyScript.lua"));

...that script file will be read in and executed immediately. In this case, you would see a message box with the friendly “hello world” message.

Note: The SessionVar.Expand action is used to retrieve the primer file path from the session variable %TempLaunchFolder%. Actions will be discussed later.

Tip: Use the dofile function to save yourself from having to re-type or re-paste a script into your projects over and over again.

require

Loads and runs a script file into the scripting engine. It is similar to dofile except that it will only load a given file once per session, whereas dofile will re-load and re-run the file each time it is used. The syntax is:

require(file_path);

If the file is a primer file located in %TempLaunchFolder%, you should not include the file extension.

So, for example, even if you do two requires in a row:

require("MyScript");
require("MyScript"); -- this line won't do anything

...only the first one will ever get executed. After that, the scripting engine knows that the file has been loaded and run, and future calls to require that file will have no effect.

Note that when using require the file must be extracted to %TempLaunchFolder% (from a primer file) and should not contain a path.

Since require will only load a given script file once per session, it is best suited for loading scripts that contain only variables and functions. Since variables and functions are global by default, you only need to “load” them once; repeatedly loading the same function definition would just be a waste of time.

This makes the require function a great way to load external script libraries. Every script that needs a function from an external file can safely require() it, and the file will only actually be loaded the first time it’s needed.

type

This function will tell you the type of value contained in a variable. It returns the string name of the variable type. Valid return values are “nil,” “number,” “string,” “boolean,” “table,” “function, ” "thread," and "userdata." For example:

a = 989;
strType = type(a); -- sets strType to "number"

a = "Hi there";
strType = type(a); -- sets strType to "string"

The type function is especially useful when writing your own functions that need certain data types in order to operate. For example, the following function uses type() to make sure that both of its arguments are numbers:

-- find the maximum of two numbers
function Max(Number1, Number2)

-- make sure both arguments are numeric
if (type(Number1) ~= "number") or (type(Number2) ~= "number") then
Dialog.Message("Error", "Please enter numbers");
return nil -- we're using nil to indicate an error condition
else
if Number1 >= Number2 then
return Number1;
else
return Number2;
end
end
end

Actions

Setup Factory comes with a large number of built-in functions. In the program interface, these built-in functions are commonly referred to as actions. For scripting purposes, actions and functions are essentially the same; however, the term “actions” is generally reserved for those functions that are built into the program and are included in the alphabetical list of actions in the online help. When referring to functions that have been created by other users or yourself, the term “functions” is preferred.


Debugging Your Scripts

Scripting (or any kind of programming) is relatively easy once you get used to it. However, even the best programmers make mistakes, and need to iron the occasional wrinkle out of their code. Being good at debugging scripts will reduce the time to market for your projects and increase the amount of sleep you get at night. Please read this section for tips on using Setup Factory as smartly and effectively as possible!

This section will explain Setup Factory’s error handling methods as well as cover a number of debugging techniques.

Error Handling

All of the built-in Setup Factory actions use the same basic error handling techniques. However, this is not necessarily true of any third-party functions, modules, or scripts—even scripts developed by Indigo Rose Corporation that are not built into the product. Although these externally developed scripts can certainly make use of Setup Factory's error handling system, they may not necessarily do so. Therefore, you should always consult a script or module's author or documentation in order to find out how error handling is, well, handled.

There are two kinds of errors that you can have in your scripts when calling Setup Factory actions: syntax errors, and functional errors.

Syntax Errors

Syntax errors occur when the syntax (or “grammar”) of a script is incorrect, or a function receives arguments that are not appropriate. Some syntax errors are caught by Setup Factory when you build or preview your Application.

For example, consider the following script:

foo =

This is incorrect because we have not assigned anything to the variable foo—the script is incomplete. This is a pretty obvious syntax error, and would be caught by the scripting engine at build time (when you build your project).

Another type of syntax error is when you do not pass the correct type or number of arguments to a function. For example, if you try and run this script:

Dialog.Message("Hi There");

...the project will build fine, because there are no obvious syntax errors in the script. As far as the scripting engine can tell, the function call is well formed. The name is valid, the open and closed parentheses match, the quotes are in the right places, and there’s even a terminating semi-colon at the end. Looks good!

However, at run time you would see something like the following:

Looks like it wasn’t so good after all. Note that the message says two arguments are required for the Dialog.Message function. Ah. Our script only provided one argument.

According to the function prototype for Dialog.Message, it looks like the function can actually accept up to five arguments:

Looking closely at the function prototype, we see that the last three arguments have default values which will be used if those arguments are omitted from the function call. The first two arguments—Title and Text—don’t have default values, so they cannot be omitted without generating an error. To make a long story short, it’s okay to call the Dialog.Message action with anywhere from 2 to 5 arguments...but 1 argument isn’t enough.

Fortunately, syntax errors like these are usually caught at build time or when you test your Application. The error messages are usually quite clear, making it easy for you to locate and identify the problem.

Functional Errors

Functional errors are those that occur because the functionality of the action itself fails. They occur when an action is given incorrect information, such as the path to a file that doesn’t exist. For example, the following code will produce a functional error:

filecontents = TextFile.ReadToString("this_file_don't exist.txt");

If you put that script into an event right now and try it, you will see that nothing appears to happen. This is because Setup Factory’s functional errors are not automatically displayed the way syntax errors are. We leave it up to you to handle (or to not handle) such functional errors yourself.

The reason for this is that there may be times when you don’t care if a function fails. In fact, you may expect it to. For example, the following code tries to remove a folder called C:\My Temp Folder:

Folder.Delete("C:\\My Temp Folder");

However, in this case you don’t care if it really gets deleted, or if the folder didn’t exist in the first place. You just want to make sure that if that particular folder exists, it will be removed. If the folder isn’t there, the Folder.Delete action causes a functional error, because it can’t find the folder you told it to delete...but since the end result is exactly what you wanted, you don’t need to do anything about it. And you certainly don’t want the user to see any error messages.

Conversely, there may be times when it is very important for you to know if an action fails. Say for instance that you want to copy a very important file:

File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");

In this case, you really want to know if it fails and may even want to exit the program or inform the user. This is where the Debug actions come in handy. Read on.

Debug Actions

Setup Factory comes with some very useful functions for debugging your applications. This section will look at a number of them.

Application.GetLastError

This is the most important action to use when trying to find out if a problem has occurred. At run time there is always an internal value that stores the status of the last action that was executed. At the start of an action, this value is set to 0 (the number zero). This means that everything is OK. If a functional error occurs inside the action, the value is changed to some non-zero value instead.

This last error value can be accessed at any time by using the Application.GetLastError action.

The syntax is:

last_error_code = Application.GetLastError();

Here is an example that uses this action:

File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");

error_code = Application.GetLastError();
if (error_code ~= 0) then
-- some kind of error has occurred!
Dialog.Message("Error", "File copy error: "..error_code);
Application.Exit();
end

The above script will inform the user that an error occurred and then exit the installation. This is not necessarily how all errors should be handled, but it illustrates the point. You can do anything you want when an error occurs, like calling a different function or anything else you can dream up.

The above script has one possible problem. Imagine the user seeing a message like this:

It would be much nicer to actually tell them some information about the exact problem. Well, you are in luck! At run time there is a table called _tblErrorMessages that contains all of the possible error messages, indexed by the error codes. You can easily use the last error number to get an actual error message that will make more sense to the user than a number like “1021.”

For example, here is a modified script to show the actual error string:

File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");

error_code = Application.GetLastError();
if (error_code ~= 0) then
-- some kind of error has occurred!
Dialog.Message("Error", "File copy error: " ..
_tblErrorMessages[error_code]);
Application.Exit();
end

Now the script will produce the following error message:

Much better information!

Just remember that the value of the last error gets reset every time an action is executed. For example, the following script would not produce an error message:

File.Copy("C:\\Temp\\My File.dat","C:\\Temp\\My File.bak");

-- At this point Application.GetLastError() could be non-zero, but...

Dialog.Message("Hi There","Hello World");

-- Oops, now the last error number will be for the Dialog.Message action,
-- and not the File.Copy action. The Dialog.Message action will reset the
-- last error number to 0, and the following lines will not catch any
-- error that happened in the File.Copy action.

error_code = Application.GetLastError();

if (error_code ~= 0) then
-- some kind of error has occurred!
Dialog.Message("Error",
"File copy error: "..
_tblErrorMessages[error_code]);
Application.Exit();
end

Debug.ShowWindow

The Setup Factory runtime has the ability to show a debug window that can be used to display debug messages. This window exists throughout the execution of your installation, but is only visible when you tell it to be.

The syntax is:

Debug.ShowWindow(show_window);

...where show_window is a Boolean value. If true, the debug window is displayed, if false, the window is hidden. For example:

-- show the debug window
Debug.ShowWindow(true);

If you call this script, the debug window will appear on top of your installation, but nothing else will really happen. That’s where the following Debug actions come in.

Debug.Print

This action prints the text of your choosing in the debug window. For example, try the following script:

Debug.ShowWindow(true);

for i = 1, 10 do
Debug.Print("i = " .. i .. "\r\n");
end

The “\r\n” part is actually two escape sequences that are being used to start a new line. (This is technically called a “carriage return/linefeed” pair.) You can use \r\n in the debug window whenever you want to insert a new line.

The above script will produce the following output in the debug window:

You can use this method to print all kinds of information to the debug window. Some typical uses are to print the contents of a variable so you can see what it contains at run time, or to print your own debug messages like “inside outer for loop” or “foo() function started.” Such messages form a trail like bread crumbs that you can trace in order to understand what’s happening behind the scenes in your project. They can be invaluable when trying to debug your scripts or test your latest algorithm.

Debug.SetTraceMode

Setup Factory can run in a special “trace” mode at run time that will print information about every line of script that gets executed to the debug window, including the value of Application.GetLastError() if the line involves calling a built-in action. You can turn this trace mode on or off by using the Debug.SetTraceMode action:

Debug.SetTraceMode(turn_on);

...where turn_on is a Boolean value that tells the program whether to turn the trace mode on or off.

Here is an example:

Debug.ShowWindow(true);
Debug.SetTraceMode(true);

for i = 1, 3 do
Dialog.Message("Number", i);
end

File.Copy("C:\\fake_file.ext", "C:\\fake_file.bak");

Running that script will produce the following output in the debug window:

Notice that every line produced by the trace mode starts with [number]: This is so you can tell them apart from any lines you send to the debug window with Debug.Print. The text after [number]: is the script that is currently being executed.

Turning trace mode on is something that you will not likely want to do in your final, distributable installation, but it can really help find problems during development.

Debug.GetEventContext

This action is used to get a descriptive string about the event that is currently being executed. This can be useful if you define a function in one place but call it somewhere else, and you want to be able to tell where the function is being called from at any given time. For example, if you execute this script from your project's On Startup event:

Dialog.Message("Event Context", Debug.GetEventContext());

...you will see something like this:

Dialog.Message

This brings us to good ole’ Dialog.Message. You have seen this action used throughout this document, and for good reason. This is a great action to use throughout your code when you are trying to track down a problem.


Final Thoughts

Hopefully this document has helped you to understand scripting in Setup Factory. Once you get the hang of it, it is a really fun, powerful way to get things done.

Other Resources

Here is a list of other places that you can go for help with scripting in Setup Factory.

Help File

The Setup Factory help file is packed with good reference material for all of the actions and events supported by Setup Factory , and for the design environment itself. You can access the help file at any time by choosing Help > Setup Factory Help from the menu.

Another useful tip: if you are in the script editor and you want to learn more about an action, simply click on the action and hit the F1 key on your keyboard.

User’s Guide

The user’s guide is a fantastic way to get started with Setup Factory. It is written in an easy-to-follow tutorial format, teaching you about events, actions and scripts. You’ll be off and running in no time! You can access the user’s guide by choosing Help > User's Guide from the menu.

Indigo Rose Web Site

The Indigo Rose Web site is located at http://www.indigorose.com. Be sure to check out the user forums where you can read questions and answers by fellow users and Indigo Rose staff as well as ask questions of your own.

A quick way to access the online forums is to choose Help > User Forums from the menu.

Indigo Rose Technical Support

If you need help with any scripting concepts or have a mental block to push through, feel free to visit http://www.indigorose.com for available support options. Although we can't write scripts for you or debug your specific scripts, we will be happy to answer any general scripting questions that you have.

The Lua Web Site

Setup Factory’s scripting engine is based on a popular scripting language called Lua. Lua is designed and implemented by a team at Tecgraf, the Computer Graphics Technology Group of PUC-Rio (the Pontifical Catholic University of Rio de Janeiro in Brazil). You can learn more about Lua and its history at the official Lua web site:

http://www.lua.org

This is also where you can find the latest documentation on the Lua language, along with tutorials and a really friendly community of Lua developers.

Note: There may be other built-in functions that exist in Lua and in Setup Factory that are not officially supported in Setup Factory. These functions, if any, are documented in the Lua 5.1 Reference Manual.

Only the functions listed in the online help are supported by Indigo Rose Software. Any other “undocumented” functions that you may find in the Lua documentation are not supported. Although these functions may work, you must use them entirely on your own.


Tips

Helpful Tips

Contents

Please select one of the following subjects:

Naming Variables

Using Variables

Using Comments

Using Whitespace


Naming Variables

Helpful Tips

Contents Naming Variables

You can name your variables almost anything you like, but there are a few rules and guidelines you should follow:

  1. Variable names can only contain letters, digits and underscores.

    Variable names can be made up of any combination of letters, digits and underscores as long as they do not begin with a number and do not conflict with any reserved keywords.

  2. Variable names are case sensitive.

    The names MyVar and myvar each refer to a different variable.

  3. Don't use any hyphens (-) in your variable names.

    The hyphen is used as an operator in Setup Factory. If you put an operator in a variable name, it will "break up" the variable into two separate variables, resulting in a syntax error (if you're lucky) or some kind of unexpected behaviour at run time. For example, Foo-Bar would be seen as subtracting the value of "Bar" from the value of "Foo" using the "-" operator.

  4. Try to use meaningful names.

    For example, if you read a product's installation date from the Registry, naming the variable Greegleborg452sx probably isn't a good idea. Use a variable name like InstallDate instead.

  5. Use prefixes to your advantage.

    A common tactic among programmers is to use short prefixes like "str" and "n" to mark variables according to what kind of data they contain—such as string or numeric values. Although Setup Factory's variables can hold any type of value at any time, it can still be helpful to use prefixes in your variable names. For example, using this system the name strResult would be used to contain a string, and the name nResult would be used to store a number. Prefixes help make your intentions clear in such cases where the name is somewhat ambiguous on its own.

  6. Be consistent.

    If you start out with UserName and UserAge, don't name your third variable WhereTheUserGoesToWork. A name like UserCompany will be easier to remember when you find yourself asking "what did I name that variable, again?"

  7. Don't use any of the action category names.

    Action names are made up of a category, like Application or File, followed by a dot and a function name, like Exit or Copy. For example, the Application.Exit action is located in the "Application" category, and the File.Copy action is located in the "File" category.

    Using a variable name like "Application" or "File" will cause all of the actions in that category to be inaccessible. This is because the action names are implemented as tables containing functions. For example, the File category is internally represented by a table containing the various file functions like Copy, Find, and Open.

    Since assigning a value to a variable overwrites any value that is already in the variable, assigning a value to a variable named "File" will replace the File category with your value.

    So, as a general rule, never name your variables anything that appears to the left of a period in an action name.

  8. Don't assign a value to a built-in variable by mistake.

    For example, assigning a value to a variable called _SystemFolder would override the built-in variable with the same name. Take time to familiarize yourself with the list of built-in global variables so you don't use any of them by accident.

  9. Don't use the same variable name twice unless you mean to.

    Using a name twice is fine if you're assigning a value to a variable in one place, and accessing that value in another. Just be careful not to unintentionally give the same name to two variables if they're being used to represent two different things.

    Of course, it's okay to assign a value to a variable twice if you want its value to change. In that case, the first value will only be in effect until the second one "overwrites" it.

  10. When in doubt, double-check.

    A common mistake is to name a variable one thing in one part of your project, and start calling it something else later. If you're not sure what name you used, double-check by going back to the place where you defined the variable.


Using Variables

Helpful Tips

Contents Using Variables

Here are some general notes on using variables:

  1. Variables are automatically "created" the first time a value is assigned to them.

  2. Variables are essentially typeless. You don't have to "declare" variables to be of a specific type, like in some programming languages. Instead, variables can hold any type of value. You can freely assign a string to a variable that currently contains a number, and vice-versa. (This doesn't mean that types aren't important...the type of the value itself still matters for actions and functions and such.)

  3. Variables are global by default. This means that once a variable is created, it is available throughout your project (unless you specifically make it a local variable).

Note: Variables persist throughout your installation. This means that variables hold their values across events. If you assign a value to a variable on one event, it will still have that value on another event—and another—and another—until eventually you assign something else to that variable.

  4. Once a value has been assigned to a variable, it will continue to contain that value until you assign something else to it.

  5. Order is important.

    When creating and using variables, be sure to think about when and where they will be used, and what their values will be at that point in time. A variable that is only assigned a value at the end of the install won't have a value when your setup starts up.

    For example, let's say you use a Dialog.Input action that asks the user for their name and stores it in a variable called UserName. It's important to realize that UserName won't contain the user's name until after that Dialog.Input action is performed. If the action is only performed after installing, UserName won't have a value before installing.

    The same is true for using variables within a script. When you assign a value to a variable, the value doesn't get assigned to the variable until that line of script is performed; in other words, it's value is only available to the actions that come "later." If you try to use the variable in an action higher "up" in the same script, or use it in another event that happens "earlier," the variable either won't have a value yet, or it won't have the value you expected it to have, and your setup will either generate an error or not behave as you intended. (This is why it's important to test your setup thoroughly before releasing it to the public.)

    A variable is only available to the parts of the your application that are performed after the variable is created. If you want to use a variable in an action later in the install, make sure a value is assigned to the variable before that action is performed.

  6. The built-in variables are listed along with all of the actions and constants when you press Ctrl+Space in the action editor.


Using Comments

Helpful Tips

Contents Using Comments

Comments are just bits of text that are completely ignored by Setup Factory. You can use comments to add notes to your scripts in order to make them easier to understand.

Note: Because the text will be ignored, you can write anything you want in a comment, and it will have no effect on how your application operates.

In Setup Factory, anything after two dashes (--) on a line is a comment. You can either put comments on their own line, like this:

-- Assign 10 to variable abc
abc = 10;

...or put them at the end of a line, like this:

abc = 10; -- assign 10 to abc

Both of the above examples do the exact same thing—the comments do not affect the script in any way.

You can also create multi-line comments by putting paired square brackets ([[ and ]]) around the comment text, like this:

--[[ This is
a multi-line
comment ]]
abc = 10;

Note: Comments are displayed in a different color that makes them easy to recognize in the action editor. (The comments are displayed in green by default, but you can change this color in the action editor settings.)

Comments Save You Time and Effort

You should make a habit of adding comments to your scripts as you build them. If adding comments seems like a waste of time, consider how much time you will spend working on these scripts in the future. Complex scripts that make perfect sense to you now might take a few minutes to interpret the next time you need to make changes to a project. A few comments written while things are fresh in your mind can minimize the amount of re-thinking required.

Comments are especially important in a multi-user environment. If it's foreseeable at all that someone else may need to work on your project in the future, do your organization a favor and document your actions well.

Here are some tips for using comments:

  • Use comments to summarize large blocks of actions. This way, you only have to read the comment to know what the actions do. It's easier to read one line of text than it is to decipher a long list of actions.

  • Use comments to explain why an action is needed. This is especially important when the purpose of an action isn't obvious.

  • Use comments to highlight important actions, or to label different parts of your scripts so they're easier to find.

  • Use comments in a team environment to help keep track of changes (and who made them).

  • Use comments to document the decision process that led you to choose one approach over another. This could save you time if you ever find yourself considering other approaches again.

  • Use comments appropriately. Don't waste time explaining simple actions that are readily apparent.

Think of comments as investing a little bit of time now to save you a lot of time over the long run. You only have to write a comment once, but you will benefit from the comment many times over. In the long run, well-written comments will save you time, time and time again.

Tip: Use comments. You'll thank us later.


Using Whitespace

Helpful Tips

Contents Using Whitespace

"Whitespace" is a term programmers use to describe things like blank lines, tab characters and spaces that are used to improve the readability of their code. You can use whitespace to make your Setup Factory scripts easier to read.

Unless they are contained within a string, whitespace characters (like spaces and tabs) are completely ignored by the install at run time. Their only purpose is to allow you to separate and format your actions a little and make your scripts easier to read.

For example, separating groups of actions with one or more blank lines makes it easier to recognize that the actions are meant to work together as a group. This is especially useful when combined with comments...a single comment can explain an entire group actions this way. Take a look at the following script:

Debug.ShowWindow(true);
file = _TempFolder .. "\\MyTempFile.tmp";
-- convert that path into its various parts
path_parts = String.SplitPath(file);
-- display the parts on the debug window
Debug.Print("Drive: " .. path_parts.Drive .. "\r\n");
Debug.Print("Folder: " .. path_parts.Folder .. "\r\n");
Debug.Print("Filename: " .. path_parts.Filename .. "\r\n");
Debug.Print("Extension: " .. path_parts.Extension .. "\r\n");
-- get the file's current attributes
attrib = File.GetAttributes( file );
-- override a couple of the values in the table
attrib.ReadOnly = true;
attrib.Hidden = false;
-- set the modified attributes back to the file
File.SetAttributes( file, attrib );

A bit hard to read, isn't it?

Now here's the same script with a few blank lines added:

Debug.ShowWindow(true);

file = _TempFolder .. "\\MyTempFile.tmp";

-- convert that path into its various parts
path_parts = String.SplitPath(file);

-- display the parts on the debug window
Debug.Print("Drive: " .. path_parts.Drive .. "\r\n");
Debug.Print("Folder: " .. path_parts.Folder .. "\r\n");
Debug.Print("Filename: " .. path_parts.Filename .. "\r\n");
Debug.Print("Extension: " .. path_parts.Extension .. "\r\n");

-- get the file's current attributes
attrib = File.GetAttributes( file );

-- override a couple of the values in the table
attrib.ReadOnly = true;
attrib.Hidden = false;

-- set the modified attributes back to the file
File.SetAttributes( file, attrib );

The whitespace makes it much easier to read.

Block Indentation

Another common use of whitespace is to make script blocks easier to see.

A block is a section of script that is controlled or affected by a control structure, such as an if statement or a while loop. For example, in an if statement, the block consists of the lines of script "inside" the if statement, that are only executed if that if statement's test is found to be true:

if(foo == true) then
-- tell the user foo is true
Dialog.Message("Hey User", "foo is true!");
end

In the example above, the two indented lines form a script "block." Technically, a block doesn't have to be indented, but it's common practice to do so, and it really makes it easier to see the part that will be affected by the if statement in the script.

Setup Factory's action editor makes it easy to add this kind of indentation to your scripts. To indent your first line in a block, just press the tab key at the start of the line. This will move the cursor over by one "level" of indentation to the right. Then continue adding lines to the block. Whenever you press Enter on a line that is indented, the editor automatically positions your cursor at the same level of indentation on the next line.

Tip: You can even indent or unindent multiple lines at once, by selecting the lines and pressing Tab (to increase the level of indentation) or pressing Shift+Tab (to decrease the level of indentation).

Indentation is especially important when there are multiple levels involved. For example, here is a short script that has a nested for loop (i.e. one for loop inside another) and a bunch of if statements. First let's see the script with no indentation:

Debug.ShowWindow(true);
if bCount then
Debug.Print("\r\nCounting to a hundred five times...\r\n");
for j = 5, 1, -1
if(j == 1) then
Debug.Print("\r\n\r\nThis is the last time!\r\n");
else
Debug.Print("\r\n\r\n" .. j - 1 .. " more times to go!");
end
for i = 1, 100
Debug.Print(i.."\r\n");
if count == 50 then
Debug.Print("We're half way to a hundred!\r\n")
end
end
end
end

Now here's the script with standard block formatting:

Debug.ShowWindow(true);
if bCount then
Debug.Print("\r\nCounting to a hundred five times...\r\n");
for j = 5, 1, -1
if(j == 1) then
Debug.Print("\r\n\r\nThis is the last time!\r\n");
else
Debug.Print("\r\n\r\n" .. j - 1 .. " more times to go!");
end
for i = 1, 100
Debug.Print(i.."\r\n");
if count == 50 then
Debug.Print("We're half way to a hundred!\r\n")
end
end
end
end

See how the indentation makes it easier to see the different blocks?


Program Reference

Contents

Welcome to the Setup Factory program reference!

Please select one of the following subjects:

  • Action Editor

  • Actions

  • Build Error Codes

  • Build Settings

  • Command Line Options

  • Controls

  • Files

  • Filters Manager

  • Folder References

  • Installing on Windows Vista or Later

  • Languages

  • Miscellaneous

  • Packages

  • Preferences

  • Program Menus

  • Project File Properties

  • Project Settings

  • Project Wizard

  • Resources

  • Screens

  • Screen Types

  • Security

  • Setup Return Codes

  • Tools

  • Resources

  • Uninstall Screens

  • Uninstall Settings

  • Variables


Action Editor - Overview

Action Editor

Overview Interface Special Features Events

The action editor is a dialog where you can add actions or scripts to events in Setup Factory.

You can use its interface to add actions by either typing them in or by clicking the Add Action button.

By adding actions to different events, you can control when the actions are performed during your install.

A typical action editor view of a screen's actions:

Note: Depending on what events are available for any given screen, the actual action editor may have different event tabs.

Tip: The above dialog is accessed by viewing any screen's properties, and clicking on the Actions tab.

A typical action editor view of a project's actions:

Tip: The above dialog is accessed by choosing Project > Actions.


Action Editor - Interface

Action Editor

Overview Interface Special Features Events

Event Tabs

There is one tab for every event that the project or screen supports. Each event represents something that can happen at run time. When an event is triggered, the actions on the corresponding tab will be performed.

Event Variables:

The variables that are automatically set whenever the current event is triggered.

Note: Event Variables are local to the current event.

Code Window

The area where you can either type in your actions, or add them through the action wizard.

Note: Once an action has been added to the code window, you can double-click it to show its properties in the Action Properties dialog. This feature can be enabled or disabled by clicking the Advanced button on the action editor.

Quick Help:

When the cursor is on an action in the code window, its action definition will be displayed in this field.

Action Help

When the cursor is on an action in the code window, its online help will be opened.

Add Action

Adds a new action to the current event through the action wizard.

Add Code

Displays a variety of code templates you can add to the code window.

Edit

Edit the action's properties after it has been added to the code window. When the cursor is on an action in the code window, the Edit button will display its properties dialog where you can modify its settings.

Bookmarks

Create and manage bookmarks in the code window so you can easily jump to specific spots in your code.

Macros

Allows you to record and save keystrokes made in the action editor so they can be replayed later where the same text is required. Macro shortcut keys can be viewed and edited on the Keyboard tab found by clicking the Advanced button and selecting Editor Settings...

Note: The macro feature will only record characters keyed directly into the action editor. It cannot recognize text added through the action wizard or autocomplete feature.

Advanced

Advanced options that are available in the action editor:

Open

Opens a script file (*.lua) and displays its contents in the code window.

Save

Saves the current script in the code window as a script file (*.lua).

Print

Prints the action script currently in the code window.

Syntax Check

This option checks the current script to make sure it is syntactically correct. It does not check for logical or other programming errors, simply syntax.

Note: You can turn on automatic syntax checking from Edit > Preferences on the Script Editor page.

Double-click Edit

Allow double-clicking on actions in the code window to edit their properties (Properties dialog will be displayed).

Note: If Double-click Edit is unchecked, double-clicking any text in the action editor simply selects the text, as in most other text editors. This option can also be set in Edit > Preferences on the Script Editor page.

Editor Settings...

Opens the action editor's Window Properties dialog where you can customize its settings.

Global Functions...

Opens a dialog where you can create any Global Functions you wish to include in your project.

Import Registry Values...

Opens the Import Registry Key/Values dialog where you can import keys or values from the Registry on your development system.

Import .REG File...

Opens a file browse dialog where you can select a .REG file that you would like to recreate using Setup Factory Registry actions.


Action Editor - Special Features

Action Editor

Overview Interface Special Features Events

Autocomplete

Autocomplete is the action editor's ability to automatically complete keywords for you when you press Tab.

As you type the first few letters of a keyword into the action editor, a black tooltip will appear nearby with the word on it. This is the action editor's autocomplete feature at work. Whenever you type something that the action editor recognizes as a keyword, it will display its best guess at what you are typing in one of those little black tooltips. Whenever one of those little black tooltips is visible, you can press the Tab key to automatically type the rest of the word.

Autocomplete Dropdown

Another feature of the autocomplete is the ability to display a dropdown of options that can be automatically completed.

If you press Ctrl+Space while your cursor is in the code window, a drop-down list will be displayed containing the names of all of the actions, constants and global variables. You can choose one of list items and then press Tab or Enter to automatically type it out for you.

Note: This dropdown cannot be accessed if your cursor is inside a set of quotes (a string).

The autocomplete dropdown is also available for completing action names after the category has been typed. For example, when you type a period after the word System, the action editor recognizes what you've typed as the beginning of an action name, and presents you with a drop-down list of all the actions that begin with "System." If you like, you can choose one of the actions from that list and then press either Tab or Enter to automatically type that word out for you. You don't have to use the drop-down list, though...you can continue typing the rest of the action yourself if you want.

Tip: Once you've typed something that the action editor recognizes as the name of an action, a little bit of Quick Help appears near the bottom of the window listing the names of the action's parameters and indicating what type of value is expected for each one.

Right-Click Insert

If your project contains many different variables and files, it's often difficult to remember the exact name or spelling that was used. The following options are available when right clicking in the code window and selecting Insert:

Variable...

Opens the Insert Variable dialog where you can select a session variable or global variable you want to insert into the code window.

File Path...

Opens a file browse dialog where you can select a file from your system whose full path you want to insert.

Folder Path...

Opens a folder browse dialog where you can select a folder from your system whose path you want to insert.

File Reference...

Opens the Insert File Reference dialog where you can insert a reference to a file in your project. This path references the location your file will be installed to, or where it exists during the install.

Search and Replace

Sometimes its useful to be able to search for specific text in the code window and replace it if needed. The following options are available when you right-click in the code window and select Advanced:

Find

Opens a Find dialog where you can specify a string of text you would like to search for in the code window.

Note: The Mark All option of the Find requires the "Show left margin" setting to be enabled in order to display the locations the string was found. You can find the "Show left margin" option on the Misc tab of the Editor Settings.

Replace

Opens the Find & Replace dialog where you can specify the string of text you would like to search for in the code window and the string you would like to replace it with.

Syntax Check

Often when developing, silly errors can be made when writing code. This option allows you to check to make sure your action script is syntactically correct on the current action event. This feature can also be found on the Advanced button of the action editor.

Note: It does not check for logical or other programming errors, simply syntax.

Action Properties

Once an action has been added to the code window, you can double-click it to show its properties in the Action Properties dialog. This feature can be enabled or disabled by clicking the Advanced button on the action editor.


Action Editor - Events

Action Editor

Overview Interface Special Features Events

Each event represents something that can happen at run time. When an event is triggered, any actions that were added to it will be performed.

Note: Some events contain special event variables that are local to the event and contain more information about the event.

There are three categories of events in Setup Factory:

  • Project Events

  • Screen Events

  • Uninstall Events

Project Events

The following describes the four main project events that are fired at different points in the install as well as an error event. You can access these events by choosing Project > Actions... from the program menu.

On Startup

This event is fired at the start of the setup, before any screens are shown. If you want to provide some visible feedback, you can use Dialog or StatusDlg actions, or instead, create the actions on a screen event.

On Pre Install

This event is fired after all of the Before Installing screens have been shown and before the installation of the files begin. No screen is visible during this process. If you want to provide some visible feedback, you can use Dialog or StatusDlg actions, or instead, create the actions on a screen event.

On Install Error

This event is fired when an error occurs during the setup allowing you to handle it in a custom way. If you would like to ignore the error that just occurred, you can call the Application.IgnoreLastError action on this event to ignore the last error that occurred. The following setup errors can be handled on this event: 120, 121, 123, 125, 126, 127, 129, 130, 140, 142, 143, 144, 145, 146, 147 and 148.

Note: This event will NOT be fired if the setup is exited through script or if the user aborted the setup.

The following event variables are automatically set whenever this event is triggered:

e_ErrorCode

(number) The numeric error code that was returned by the setup.

e_ErrorMsgID

(string) The error message string identifier of the error that was returned by the setup.

Note: In order to retrieve the message text for the error, you need to call the SetupData.GetLocalizedString action and pass it the value of e_ErrorMsgID.

On Post Install

This event is fired after all of the files have been installed - after the While Installing screen has been shown, but before the After Installing screens. No screen is visible during this process. If you want to provide some visible feedback, you can use Dialog or StatusDlg actions, or instead, create the actions on a screen event.

On Shutdown

This event is fired on completion of the install, after all of the After Installing screens have been shown. No screen is visible during this process. If you want to provide some visible feedback, you can use Dialog or StatusDlg actions, or instead, create the actions on a screen event.

Screen Events

The following describes all of the possible events that may be fired from a screen. You can find these events on the Actions tab of each screen's properties dialog.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

On Back

This event is fired when the Back button is clicked. Normally the Screen.Back action is used here.

On Cancel

This event is fired when the Cancel button, the close button on the title bar, or the Esc key is pressed. Normally the Application.Exit action is used here.

On Ctrl Message

This event is fired when any control on the screen fires a message. You can use this event to respond to any control message. To respond to the message, event variables need to be consulted.

The following event variables are automatically set whenever this event is triggered:

e_CtrlID

(number) The control id of the control that spawned the event.

e_MsgID

(number) The id of the notification message that was fired from the screen control. Each type of control contains its own unique message IDs. These message ids are defined under each control type's topic.

e_Details

(table) An optional table of details that the control might include. In order to respond to this properly you must consult the specific control type in order to determine what the contents of this table will be. If no details are included, this table will be passed as nil.

On Finish

This event is fired when a progress type of screen has completed its progress actions.

On Help

This event is fired when the Help button is clicked.

On Next

This event is fired when the Next button is clicked. Normally the Screen.Next action is used here.

On Preload

This event is fired before the screen is displayed.

Note: At this point the screen and its controls have been created so they can be accessed via Dlg***.SetProperties and Dlg***.GetProperties actions. During that process any session variables used on the screen were expanded, therefore any changes made to the session variables on the On Preload event have no effect on the screen. All changes to session variables must be made earlier in the install, or by re-setting the control's text using the Dlg***.SetProperties actions.

On Progress

This event is fired every time progress is made while installing or uninstalling files during the setup.

The following event variables are automatically set whenever this event is triggered:

e_Stage

(number) The progress stage that the install/uninstall is currently in. One of the following stages will be returned:

CONSTANT | VALUE | DESCRIPTION
INSTALL_STAGE_PREPARING | 1 | The setup is preparing to install the files.
INSTALL_STAGE_INSTALLING_FILES | 2 | The setup is in the process of installing the files.
INSTALL_STAGE_CREATING_UNINSTALL | 3 | The setup is creating the uninstall for the application.
INSTALL_STAGE_CREATING_SHORTCUTS | 4 | The setup is creating shortcuts on the user's system.
UNINSTALL_STAGE_REMOVING_FILES | 1 | The uninstall is removing files from the user's system.
UNINSTALL_STAGE_REMOVING_SHORTCUTS | 2 | The uninstall is removing shorcuts from the user's system.

e_CurrentItemText

(string) A string containing the current item's details. This text is normally displayed above the progress meter as a description of what is currently occurring in the install. For example, this text may contain the name of the current file that is being installed.

e_CurrentItemPct

(number) A value (between 1 and 100) that represents the percentage of the current process that has been completed. For example, when installing files, each file being installed will have its own percentage value returned.

e_StagePct

(number) A value (between 1 and 100) that represents the percentage of the install/uninstall stage that has been completed so far. Possible install/uninstall stages can be found in the e_Stage table above.

On Start

This event is fired from a progress type screen to start its progress actions.

Uninstall Events

On Startup

This event is fired at the start of the uninstall process, before any screens are shown. If you want to provide some visible feedback, you can use Dialog or StatusDlg actions, or instead, create the actions on a screen event.

On Pre Uninstall

This event is fired after all of the Before Uninstalling screens have been shown and before the uninstallation of the files begin. No screen is visible during this process. If you want to provide some visible feedback, you can use Dialog or StatusDlg actions, or instead, create the actions on a screen event.

On Uninstall Error

This event is fired when an error occurs during the setup's uninstall, allowing you to handle it in a custom way. If you would like to ignore the error that just occurred, you can call the Application.IgnoreLastError action on this event to ignore the last error that occurred. The following setup errors can be handled on this event: 120, 121, 123, 125, 126, 127, 129, 130, 140, 142, 143, 144, 145, 146, 147 and 148.

Note: This event will NOT be fired if the setup is exited through script or if the user aborted the setup.

The following event variables are automatically set whenever this event is triggered:

e_ErrorCode

(number) The numeric error code that was returned by the uninstall.

e_ErrorMsgID

(string) The error message string identifier of the error that was returned by the uninstall.

Note: In order to retrieve the message text for the error, you need to call the SetupData.GetLocalizedString action and pass it the value of e_ErrorMsgID.

On Post Uninstall

This event is fired after all of the files have been uninstalled - after the While Uninstalling screen has been shown but before the After Uninstalling screens. No screen is visible during this process. If you want to provide some visible feedback, you can use Dialog or StatusDlg actions, or instead, create the actions on a screen event.

On Shutdown

This event is fired on completion of the uninstall, after all of the After Uninstalling screens have been shown. No screen is visible during this process. If you want to provide some visible feedback, you can use Dialog or StatusDlg actions, or instead, create the actions on a screen event.


Actions - Overview

Actions

Overview Alphabetical List Error Codes

What are actions?

Actions are the commands that your Setup Factory installer can perform at run time. Each action is a discrete instruction that tells the installer to do something—whether it's to modify the registry, open an external document, or jump to another screen.

In other words, actions are what make your installer do stuff.

And there's a lot of stuff your installer can do! (Just have a look at the alphabetical list of actions.)

When do actions happen?

Actions are always triggered by events. An event is something that occurs at run time while the user is proceeding through your setup. This includes things like clicking on the next button on a screen (the "On Next" screen event).

Where do I find these events?

The events will appear as tabs on the action editor. There are three types of events in Setup Factory: project events, screen events and uninstall events. Below you will find an example of this:

How do I add an action?

As mentioned above, actions can be added in several places.

Actions can be added to project events by selecting Project > Actions... from the program menu.
Actions can be added to screen events by selecting the actions tab of the screen's properties dialog.
Actions can be added to the uninstall's events by selecting Uninstall > Actions... from the program menu.

Once the action editor is open, you can either type in the action directly, or click on the Add Action button to walk through the process using the New Action wizard.

How do I edit an action?

Once you've added an action, you can edit its text the same way you would edit a paragraph in Word.

Or, you can double-click the line that the action is on, to edit it using the Action Properties dialog.


Alphabetical List

Actions

Overview Alphabetical List Error Codes

Application

Application.Exit

Application.ExitScript

Application.GetInstallLanguage

Application.GetLastError

Application.GetWndHandle

Application.IgnoreLastError

Application.LoadActionPlugin

Application.LoadScript

Application.LoadValue

Application.Minimize

Application.Restore

Application.RunScriptFile

Application.SaveValue

Application.SetInstallLanguage

Application.SetLastError

Application.Sleep

Crypto

Crypto.Base64DecodeFromFile

Crypto.Base64DecodeFromString

Crypto.Base64EncodeToFile

Crypto.Base64EncodeToString

Crypto.BlowfishDecrypt

Crypto.BlowfishDecryptString

Crypto.BlowfishEncrypt

Crypto.BlowfishEncryptString

Crypto.MD5DigestFromFile

Crypto.MD5DigestFromString

Crypto.Rot13

Debug

Debug.Clear

Debug.GetEventContext

Debug.GetTraceMode

Debug.Print

Debug.SendToFile

Debug.SetTraceMode

Debug.ShowWindow

Dialog

Dialog.ComboBox

Dialog.FileBrowse

Dialog.FolderBrowse

Dialog.Input

Dialog.MaskedInput

Dialog.Message

Dialog.PasswordInput

Dialog.SplashImage

Dialog.TimedMessage

DlgBILLBOARD

DlgBillboard.AddImage

DlgBillboard.DeleteImage

DlgBillboard.FillFromFolder

DlgBillboard.GetCurrentImage

DlgBillboard.GetImageCount

DlgBillboard.GetImagePath

DlgBillboard.GetPos

DlgBillboard.GetProperties

DlgBillboard.GetSize

DlgBillboard.GoToImage

DlgBillboard.IsEnabled

DlgBillboard.IsVisible

DlgBillboard.Navigate

DlgBillboard.Pause

DlgBillboard.Play

DlgBillboard.SetEnabled

DlgBillboard.SetPos

DlgBillboard.SetProperties

DlgBillboard.SetSize

DlgBillboard.SetVisible

DLGButton

DlgButton.GetProperties

DlgButton.SetProperties

DLGCheckbox

DlgCheckBox.GetProperties

DlgCheckBox.SetProperties

DLGcombobox

DlgComboBox.AddItem

DlgComboBox.GetItemData

DlgComboBox.GetItemText

DlgComboBox.GetProperties

DlgComboBox.InsertItem

DlgComboBox.RemoveItem

DlgComboBox.SetItemData

DlgComboBox.SetProperties

Dlgeditfield

DlgEditField.GetProperties

DlgEditField.SetProperties

DlgGROUPBOX

DlgGroupBox.GetProperties

DlgGroupBox.SetProperties

DlgListbox

DlgListBox.AddItem

DlgListBox.DeleteItem

DlgListBox.FindItem

DlgListBox.GetCount

DlgListBox.GetItemProperties

DlgListBox.GetProperties

DlgListBox.GetSelected

DlgListBox.GetSelectedCount

DlgListBox.InsertItem

DlgListBox.SetItemProperties

DlgListBox.SetProperties

DlgListBox.SetUpdate

DlgProgressbar

DlgProgressBar.GetPos

DlgProgressBar.GetProperties

DlgProgressBar.GetRange

DlgProgressBar.SetPos

DlgProgressBar.SetProperties

DlgProgressBar.SetRange

DlgProgressBar.SetStep

DlgProgressBar.Step

Dlgradiobutton

DlgRadioButton.GetProperties

DlgRadioButton.SetProperties

Dlgscrollingtext

DlgScrollingText.AppendLine

DlgScrollingText.GetProperties

DlgScrollingText.SetProperties

DlgSelectpackages

DlgSelectPackages.GetCategoryProperties

DlgSelectPackages.SetCategoryProperties

DlgSelectPackages.UpdateDisplay

DlgStatictext

DlgStaticText.GetProperties

DlgStaticText.SetProperties

DLL

DLL.CallFunction

DRIVE

Drive.Eject

Drive.Enumerate

Drive.GetFreeSpace

Drive.GetInformation

Drive.GetSize

Drive.GetType

Drive.GetUsedSpace

File

File.Copy

File.Delete

File.DeleteOnReboot

File.DoesExist

File.ExploreFolder

File.Find

File.GetAttributes

File.GetCRC

File.GetDefaultViewer

File.GetShortName

File.GetSize

File.GetVersionInfo

File.Install

File.IsInUse

File.Move

File.MoveOnReboot

File.Open

File.OpenEmail

File.OpenURL

File.Print

File.Rename

File.Run

File.RunAs

File.RunOnReboot

File.SetAttributes

File.SetPermissions

FOLDER

Folder.Create

Folder.Delete

Folder.DeleteTree

Folder.DoesExist

Folder.Find

Folder.GetCurrent

Folder.Rename

Folder.SetCurrent

HTTP

HTTP.Download

HTTP.DownloadSecure

HTTP.GetConnectionState

HTTP.GetFileSize

HTTP.GetFileSizeSecure

HTTP.GetHTTPErrorInfo

HTTP.Submit

HTTP.SubmitSecure

HTTP.TestConnection

INIFILE

INIFile.DeleteSection

INIFile.DeleteValue

INIFile.GetSectionNames

INIFile.GetValue

INIFile.GetValueNames

INIFile.SetValue

Math

Math.Abs

Math.Acos

Math.Asin

Math.Atan

Math.Atan2

Math.Ceil

Math.Cos

Math.Deg

Math.Exp

Math.Floor

Math.Frexp

Math.HexToNumber

Math.Ldexp

Math.Log

Math.Log10

Math.Max

Math.Min

Math.Mod

Math.Pow

Math.Rad

Math.Random

Math.RandomSeed

Math.Round

Math.Sin

Math.Sqrt

Math.Tan

MSI

MSI.ApplyPatch

MSI.CloseHandle

MSI.ConfigureFeature

MSI.ConfigureProduct

MSI.ConfigureProductEx

MSI.EnableLog

MSI.EnumClients

MSI.EnumComponents

MSI.EnumFeatures

MSI.EnumPatches

MSI.EnumProducts

MSI.EnumRelatedProducts

MSI.GetComponentPath

MSI.GetFeatureInfo

MSI.GetFeatureUsage

MSI.GetFileVersion

MSI.GetMSIVersion

MSI.GetPatchInfo

MSI.GetProductCode

MSI.GetProductInfo

MSI.GetProductProperty

MSI.GetShortcutTarget

MSI.GetUserInfo

MSI.InstallMissingComponent

MSI.InstallMissingFile

MSI.InstallProduct

MSI.LocateComponent

MSI.OpenPackage

MSI.OpenProduct

MSI.QueryFeatureState

MSI.QueryProductState

MSI.ReinstallFeature

MSI.ReinstallProduct

MSI.RunMsiexec

MSI.SetInternalUI

MSI.VerifyPackage

ODBC

ODBC.ConfigDataSource

ODBC.InstallDriver

ODBC.InstallManager

ODBC.UninstallDriver

ODBC.UninstallManager

REGISTRY

Registry.CreateKey

Registry.DeleteKey

Registry.DeleteValue

Registry.DoesKeyExist

Registry.GetAccess

Registry.GetKeyNames

Registry.GetValue

Registry.GetValueNames

Registry.GetValueType

Registry.SetValue

screen

Screen.Back

Screen.End

Screen.GetFocus

Screen.GetLocalizedString

Screen.GetProperties

Screen.Jump

Screen.Next

Screen.Previous

Screen.SetFocus

Screen.SetLocalizedString

Screen.SetStartScreen

Screen.StartTimer

Screen.StopTimer

SERVICE

Service.Continue

Service.Create

Service.Delete

Service.Pause

Service.Query

Service.Start

Service.Stop

sessionvar

SessionVar.Expand

SessionVar.Get

SessionVar.Remove

SessionVar.Set

setupdata

SetupData.CalculateRequiredSpace

SetupData.GetAppShortcutFolderPath

SetupData.GetFileList

SetupData.GetLocalizedString

SetupData.GetPackageList

SetupData.GetPackageProperties

SetupData.GetSerialListNames

SetupData.IsValidSerialNumber

SetupData.SetLocalizedString

SetupData.SetPackageProperties

SetupData.WriteToLogFile

SHELL

Shell.CreateShortcut

Shell.DeleteShortcut

Shell.Execute

Shell.GetFolder

Statusdlg

StatusDlg.GetAutoSize

StatusDlg.GetMeterPos

StatusDlg.Hide

StatusDlg.IsCancelled

StatusDlg.SetAutoSize

StatusDlg.SetCancelled

StatusDlg.SetMessage

StatusDlg.SetMeterPos

StatusDlg.SetMeterRange

StatusDlg.SetStatusText

StatusDlg.SetTitle

StatusDlg.Show

StatusDlg.ShowCancelButton

StatusDlg.ShowProgressMeter

StRING

String.AbbreviateFilePath

String.Asc

String.Char

String.Compare

String.CompareFileVersions

String.CompareNoCase

String.Concat

String.Find

String.GetFormattedSize

String.Left

String.Length

String.Lower

String.MakePath

String.Mid

String.Repeat

String.Replace

String.ReverseFind

String.Right

String.SplitPath

String.ToNumber

String.TrimLeft

String.TrimRight

String.Upper

SYSTEM

System.EnumerateProcesses

System.GetDate

System.GetDefaultLangID

System.GetDisplayInfo

System.GetLANInfo

System.GetMemoryInfo

System.GetOSName

System.GetOSProductInfo

System.GetOSVersionInfo

System.GetTime

System.GetUserInfo

System.GetUserSID

System.Is64BitOS

System.IsSystemRestoreAvailable

System.Reboot

System.RegisterActiveX

System.RegisterFont

System.RegisterTypeLib

System.RemoveRestorePoint

System.SetRestorePoint

System.TerminateProcess

System.UnregisterActiveX

System.UnregisterFont

TABLE

Table.Concat

Table.Count

Table.Insert

Table.Remove

Table.Sort

textfile

TextFile.ReadToString

TextFile.ReadToTable

TextFile.WriteFromString

TextFile.WriteFromTable

uninstalldata

UninstallData.AddItem

UninstallData.GetConfigurationFile

UninstallData.GetItem

UninstallData.GetItemList

UninstallData.RemoveItem

UninstallData.SetConfigurationFile

Window

Window.Close

Window.EnumerateProcesses

Window.EnumerateTitles

Window.GetPos

Window.GetSize

Window.Hide

Window.Maximize

Window.Minimize

Window.Restore

Window.SetOrder

Window.SetPos

Window.SetSize

Window.SetText

Window.Show

XML

XML.Count

XML.GetAttribute

XML.GetAttributeNames

XML.GetElementNames

XML.GetElementXML

XML.GetValue

XML.GetXML

XML.InsertXML

XML.Load

XML.RemoveAttribute

XML.RemoveElement

XML.Save

XML.SetAttribute

XML.SetValue

XML.SetXML


Application.Exit

Overview Examples

Application.Exit (

number ReturnCode = 0 )

Description

Exits the installer and returns an optional return code.

Tip: You can use this action to exit the install process at any point.

Parameters

ReturnCode

(number) The optional return code you want to set for the setup.exe's process.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.

See also: Related Actions


Application.ExitScript

Application.ExitScript (

)

Description

Breaks out of the current block of script being executed.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.GetInstallLanguage

table Application.GetInstallLanguage (

)

Description

Returns a table containing the primary and secondary language ID that is being used by your installation. The value returned by Application.GetInstallLanguage will always be a value for a language that you added to your project using the Language Manager. It will never contain values for languages that were not explicitly included in the setup.

Note: This action may return a different result than System.GetDefaultLangID.

Parameters

None.

Returns

(table) A table containing the current install language, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Primary | number | The primary language ID of the current language (in decimal format). You can access this value using tb.Primary.
Secondary | number | The secondary language ID of the current language (in decimal format). It can be accessed using tb.Secondary.

If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Application.GetLastError

number Application.GetLastError (

)

Description

Returns the last error code.

Tip: Use this to check whether an error occurred while performing the last action.

Parameters

None.

Returns

(number) The error code for the last action that was performed. (0 if the action succeeded, a number greater than 0 if the action failed.)

See Error Codes for the complete list of error codes.

Note: All of the error code messages are stored in a table called _tblErrorMessages and can be accessed by their error code index. For example, accessing the table index _tblErrorMessages[1000] will access the error code string "The specified file could not be found."

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Application.GetWndHandle

number Application.GetWndHandle (

)

Description

Returns the numeric window handle for the main installer window. To retrieve the window handle of individual screens, use Screen.GetProperties. The main window's window handle is useful when you want to perform an action on the entire application, such as minimizing, closing, etc.

Note: This action returns the window handle for the entire setup, whether a background window is visible or not.

Parameters

None.

Returns

(number) The numeric window handle for the installer. If an error occurs, -1 will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Application.IgnoreLastError

Application.IgnoreLastError (

)

Description

This action is used to ignore the last setup error that occurred, and will only work if called from the On Install Error or On Uninstall Error events.

Parameters

None.

Returns

Nothing.


Application.LoadActionPlugin

Application.LoadActionPlugin (

string Filename )

Description

Loads an action plugin file (.lmd).

Note: Normally you would choose Resources > Plugins... to add an action plugin. This action is only intended to handle special situations where you need more control over when the plugin is loaded.

Note: The plugin platform must match the chosen setup platform (32-bit or 64-bit). If they are different, the action plugin will fail to load.

Action plugins allow you to extend the functionality of Setup Factory with new actions. Refer to the action plugin's documentation for information on what features it adds and how to use them.

Tip: Action plugin files must be extracted before they can be loaded. If you need access to a plugin file early in the install, you can include it as a primer file.

Parameters

Filename

(string) The path to the action plugin file (.lmd).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.LoadScript

Application.LoadScript (

string Filename )

Description

Loads and executes an external script file (.lua) if it hasn't been loaded already.

A script file is simply a text file containing Setup Factory script.

Note: The contents of the script file will only be executed once per session, no matter how many times it is loaded.

Parameters

Filename

(string) The path to the external script file (.lua).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.LoadValue

string Application.LoadValue (

string Section,

string Key )

Description

Loads a value that was saved with the Application.SaveValue action.

Parameters

Section

(string) The name of the "section" that the value was saved in.

Key

(string) The name of the "key" that identifies the value.

Returns

(string) The value that was loaded. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Application.Minimize

Application.Minimize (

)

Description

Minimizes the installer window to the task bar.

Note: This action is the same as pressing the minimize button ( [image] ) on the installer's title bar.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.Restore

Application.Restore (

)

Description

Restores the installer's window to the size and position it had before it was minimized.

Note: This action is the same as pressing the restore button ( [image] ) on the installer's title bar.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.RunScriptFile

Application.RunScriptFile (

string Filename )

Description

Executes the contents of an external script file (.lua).

A script file is simply a text file containing Setup Factory script.

Parameters

Filename

(string) The path to the external script file (.lua).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.SaveValue

Application.SaveValue (

string Section,

string Key,

string Value )

Description

Saves a value to the user's system so it can be retrieved later with an Application.LoadValue action.

Parameters

Section

(string) The name of the "section" that the value will be saved in.

Note: If the section doesn't exist it will be created automatically.

Key

(string) The name of the "key" that will identify the value.

Note: If a key by that name already exists, the new value will overwrite the old one.

Value

(string) The value to save.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.SetInstallLanguage

Application.SetInstallLanguage (

number Primary,

number Secondary )

Description

Sets the specified language to be the install language. This will cause all messages and screens to be displayed in the specified language from the time this action is called.

Parameters

Primary

(number) The primary language ID of the language (in decimal format) you want to set for the install.

Secondary

(number) The secondary language ID of the language (in decimal format) you want to set for the install.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.SetLastError

Application.SetLastError (

number ErrorCode )

Description

Changes the last error code.

Parameters

ErrorCode

(number) A numeric code indicating the error code you wish to set.

See Error Codes for the complete list of error codes.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.Sleep

Application.Sleep (

number Time )

Description

Causes the installation to sleep for a desired period of time.

Note: While sleeping, the installation will not respond to mouse movements, clicks, or key presses. This applies to every aspect of the installer, including but not limited to the Cancel button.

Parameters

Time

(number) The time to sleep, in milliseconds.

Tip: 1000 milliseconds = 1 second

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Base64DecodeFromFile

Crypto.Base64DecodeFromFile (

string Source,

string Destination )

Description

Decodes a base64-encoded text file and stores the result as a binary file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Source

(string) The full path to the base64-encoded text file that you want to decode.

Destination

(string) The full path and filename for the decoded binary file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Base64DecodeFromString

Crypto.Base64DecodeFromString (

string Text,

string Filename )

Description

Decodes a base64-encoded string and stores the result as a binary file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Text

(string) The base64-encoded text that you want to decode.

Filename

(string) The full path and filename for the decoded binary file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Base64EncodeToFile

Crypto.Base64EncodeToFile (

string Source,

string Destination,

number LineLen = 76 )

Description

Stores the contents of a binary file as a base64-encoded text file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Source

(string) The full path to the file that you want to encode.

Destination

(string) The full path and filename for the base64-encoded file.

LineLen

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 76.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Base64EncodeToString

string Crypto.Base64EncodeToString (

string Source,

number LineLen = 76 )

Description

Returns the contents of a binary file as a base64-encoded string.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Source

(string) The full path to the file that you want to encode.

LineLen

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 76.

Returns

(string) The contents of the specified binary file as a base64-encoded string. If the data cannot be encoded or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.BlowfishDecrypt

Crypto.BlowfishDecrypt (

string Source,

string Destination,

string Key )

Description

Creates a decrypted copy of a blowfish-encrypted file.

Parameters

Source

(string) The full path to the file that you want to decrypt.

Destination

(string) The full path and filename for the decrypted file.

Key

(string) The secret key that the data was decrypted with.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.BlowfishDecryptString

string Crypto.BlowfishDecryptString (

string Text,

string Key )

Description

Decrypts a string that was encrypted using the Crypto.BlowfishEncryptString action. (Decodes a base64-encoded string and decrypts the blowfish-encrypted data.)

Tip: You do not have to Base64Decode the string first, simply pass this action any string encoded using the Crypto.BlowfishEncryptString.

Note: Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Text

(string) The string that you want to decrypt.

Key

(string) The secret key that the data was encrypted with.

Returns

(string) The decrypted version of a string that was encrypted with a Crypto.BlowfishEncryptString action. If the data cannot be decrypted or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.BlowfishEncrypt

Crypto.BlowfishEncrypt (

string Source,

string Destination,

string Key )

Description

Creates a blowfish-encrypted copy of a file.

Parameters

Source

(string) The full path to the file that you want to encrypt.

Destination

(string) The full path and filename for the blowfish-encrypted file.

Key

(string) The secret key to encrypt the data with.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.BlowfishEncryptString

string Crypto.BlowfishEncryptString (

string Text,

string Key,

number LineLen = 0 )

Description

Blowfish encrypts a string and returns a base64-encoded string containing the encrypted data.

Note: Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Text

(string) The string that you want to encrypt.

Key

(string) The secret key to encrypt the data with.

LineLen

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 0.

Returns

(string) A base64-encoded string containing the encrypted data. If the data cannot be encrypted or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.MD5DigestFromFile

string Crypto.MD5DigestFromFile (

string Filename )

Description

Creates an MD5 message digest for a given file.

Parameters

Filename

(string) The full path to the file whose MD5 digest you want to calculate.

Note: The file can be of any type (binary or ascii).

Returns

(string) The message digest that was calculated for the file. If the message digest cannot be calculated or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.MD5DigestFromString

string Crypto.MD5DigestFromString (

string Text )

Description

Creates an MD5 message digest for a given text string.

An MD5 message digest is a 128-bit "fingerprint" or digital signature, represented by a string of 32 hex digits. Every unique string of text is guaranteed to produce a unique message digest. More importantly, it is virtually impossible to determine the original string from the digest. In other words, the MD5 calculation only works in one direction. This makes it extremely useful for storing passwords.

Instead of storing a password in plain text, you should store its MD5 digest instead. When the user enters a password, calculate the MD5 digest for the text that they entered, and compare that to the MD5 digest that was stored. If it is identical to the stored digest, then the user entered the correct password.

Since there is no way to get from the digest back to the original password, it doesn't matter if anyone sees the digest.

Note: MD5 isn't a substitute for secure passwords. Using an insecure password like "sneeze" or "equine" can still leave your application open to so-called "dictionary attacks," where the hacker simply tries the MD5 digest for every word in the dictionary. Be sure to use secure passwords like "sationicat59" or "b$fer@fe!23."

Tip: A good way to defeat dictionary attacks when using user-supplied passwords is to append a non-alphabetic string to all passwords. For example, simply append "$!%" to the end of any password before generating the MD5 digest. This way, even a really bad password like "password" will be relatively safe from dictionary attacks.

Parameters

Text

(string) The text to create the message digest for.

Returns

(string) The message digest that was calculated for the given text. If the message digest cannot be calculated or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.Rot13

string Crypto.Rot13 (

string Text )

Description

Applies a simple Ceaser-cypher ("rot13") encryption to the text.

The simple Caesar-cypher encryption replaces each English letter with the one 13 places forward or back along the alphabet, so that "Indigo Rose is cool!" becomes "Vaqvtb Ebfr vf pbby!" In other words, it "rotates" the alphabet ahead 13 characters. Most Usenet news reading and posting programs include a rot13 feature to hide text from plain sight so the user must choose to view it. (For example, to hide "spoilers" -- information that gives away some secret that readers might not want to know if they haven't already read the book, played the game, etc.)

A nice feature of rot13 is that the same action is used to encrypt and decrypt the text.

Parameters

Text

(string) The text that you want to encrypt (or decrypt).

Returns

(string) The encrypted (or decrypted) text. If the text cannot be encrypted (or decrypted) or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Debug.Clear

Debug.Clear (

)

Description

Clears the contents of the debug window.

Parameters

None.

Returns

Nothing.


Debug.GetEventContext

string Debug.GetEventContext (

)

Description

Returns a string describing the current event context, e.g. "Welcome > On Next".

Parameters

None.

Returns

(string) A string describing the current event context.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Debug.GetTraceMode

boolean Debug.GetTraceMode (

)

Description

Returns the current debug trace mode.

Parameters

None.

Returns

(boolean) True if trace mode is on, false if trace mode is off.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Debug.Print

Debug.Print (

string Text )

Description

Appends text to the bottom of the debug window.

Parameters

Text

(string) The text to add to the debug window.

Returns

Nothing.


Debug.SendToFile

number Debug.SendToFile (

string Filename,

boolean Overwrite = true )

Description

Sends the output to a text file as well as the debug dialog.

Parameters

Filename

(string) The full path to the file where the debug output will be written to.

Overwrite

(boolean) Whether the debug information will overwrite Filename, if it exists, or append to it.

VALUE | DESCRIPTION
true | Overwrite Filename if it exists. (Default)
false | Append to Filename if it exists.

Returns

(number) Returns 0 if successful, or non-zero if an error occurred.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Debug.SetTraceMode

Debug.SetTraceMode (

boolean Enable = true )

Description

Turns debug trace mode on or off.

When trace mode is on, every line of code will be traced out to the debug window, and the last error code will be printed after each action is performed.

Parameters

Enable

(boolean) Whether to turn trace mode on or off:

VALUE | DESCRIPTION
true | Turn trace mode on. (Default)
false | Turn trace mode off.

Returns

Nothing.


Debug.ShowWindow

Debug.ShowWindow (

boolean Show )

Description

Shows or hides the debug window.

Parameters

Show

(boolean) Whether to show or hide the debug window:

VALUE | DESCRIPTION
true | Show the window. (default)
false | Hide the window.

Returns

Nothing.


Dialog.ComboBox

string Dialog.ComboBox (

string Title,

string Prompt,

table Items,

string DefaultItem,

boolean SortItems = false,

boolean Editable = false,

number Icon = MB_ICONQUESTION )

Description

Presents a dialog box with a combo box control on it.

Parameters

Title

(string) The text to be displayed on the title bar of the dialog.

Prompt

(string) The text that will appear above the combo box.

Items

(table) A numerically indexed table containing the list of items that should be available in the combo box.

DefaultItem

(string) The default item that should be selected in the combo box. Use an empty string ("") for nothing to be selected.

SortItems

(boolean) Whether the items in the drop-down area should be sorted or not:

VALUE | DESCRIPTION
true | Sort the items in the drop down.
false | Don't sort the items. (Default)

Editable

(boolean) Whether the combo box text should be editable or if the user has to choose an item from the list:

VALUE | DESCRIPTION
true | The combo box text should be editable.
false | The user must choose an item from the list. (Default)

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question. (Default)
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

Returns

(string) The item that was selected from the combo box or the text that was entered if the field was editable, if the OK button is pressed. It will return "CANCEL" if the Cancel button is pressed. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.FileBrowse

table Dialog.FileBrowse (

boolean FileOpen,

string Title,

string DefaultFolder,

string FileFilters = "All Files (*.*)|*.*|",

string Filename = "",

string FileExtension = "",

boolean MultipleSelect = false,

boolean FileMustExist = false )

Description

Presents a file browse dialog to the user to collect the paths to one or more files.

Parameters

FileOpen

(boolean) Whether to make the dialog a "file open" dialog:

VALUE | DESCRIPTION
true | Dialog will be a " file open" dialog.
false | Dialog will be a "file save" dialog.

Title

(string) The text to be displayed on the dialog title bar.

DefaultFolder

(string) The default folder to browse.

Tip: You can click the browse button ( [image] ) to select a folder.

FileFilters

(string) The file type filters that will be used in the browse. Defaults to "All Files (*.*)|*.*|". These filters control which file types will be visible in the file browse dialog. For example, if you want to filter only executables, you could have "Executables (*.exe)|*.exe|". "Executables (*.exe)" is the description that will appear in the "Files of type" field on the dialog and can be any text you want. "|*.exe|" represents the file filter that will be used internally.

You can also include multiple filters that can be selected. For example, "Executables (*.exe)|*.exe|Text Files (*.txt)|*.txt|". The second filter will be available on the dialog from the drop down in the "Files of type" field.

You also have the ability to specify more than one pattern for a filter by separating the patterns with semicolons. For example, "Pictures (.png, .jpg, .tif)|*.png;*.jpg;*.tif".

Filename

(string) The file name that initially appears in the file name edit box.

FileExtension

(string) The default file extension. This will be appended to the filename in the file name edit box if the user does not supply an extension.

Note: Only used if the user types the name in.

MultipleSelect

(boolean) Whether to allow multiple selection of files:

VALUE | DESCRIPTION
true | Allow multiple selection.
false | Don't. (Default)

FileMustExist

(boolean) Whether to make sure that the file name in the edit field of the dialog exists when the user clicks "Open" or "Save."

VALUE | DESCRIPTION
true | The file must exist.
false | The file doesn't have to exist. (Default)

Returns

(table) A table containing the list of paths to the files that were selected. Each individual path can be accessed at it's table index. If the user cancels the operation (presses the cancel button), the string "CANCEL" will be returned in the table (tb[1] = "CANCEL"). If an error occurs, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Dialog.FolderBrowse

string Dialog.FolderBrowse (

string Prompt,

string DefaultFolder )

Description

Presents a folder browse dialog to the user to collect the path to a folder.

Parameters

Prompt

(string) The message text on the dialog.

DefaultFolder

(string) The default folder to browse.

Tip: You can click the browse button ( [image] ) to select a folder.

Returns

(string) The path to the folder that was selected with the folder browse dialog. If the user cancels the operation (presses the cancel button), the string "CANCEL" will be returned. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Dialog.Input

string Dialog.Input (

string Title,

string Prompt,

string DefaultText = "",

number Icon = MB_ICONQUESTION )

Description

Presents an input dialog to collect information from the user.

Parameters

Title

(string) The text to be displayed on the title bar of the dialog.

Prompt

(string) The text that will appear above the edit field.

DefaultText

(string) The default text to display in the edit field. Defaults to an empty string (no text).

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question. (Default)
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

Returns

(string) The text that was in the edit field if the OK button is pressed, or "CANCEL" if the Cancel button is pressed. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Dialog.MaskedInput

table Dialog.MaskedInput (

string Title = "",

string Prompt,

string Mask,

string DefaultText = "",

number Icon = MB_ICONQUESTION,

string PlaceHolder = " " )

Description

Presents an input dialog to collect information from the user in a specific format.

Parameters

Title

(string) The text to be displayed in the title bar of the dialog.

Prompt

(string) The text to be displayed above the edit field.

Mask

(string) The input mask to be used to control input into the edit field.

DefaultText

(string) The default text to display in the edit field. Defaults to an empty string (no text).

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question. (Default)
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

PlaceHolder

(string) Text used as a placeholder for the input mask. This can be used as sample input until the user fills the input mask. For example, if you used the telephone number input mask, you could include a sample digit as the placeholder such as 9. At runtime it would appear as (999) 999-9999 until the user replaced these digits with their own. The default is a blank space.

Returns

(table) A table containing the user input text, indexed by the following keys:

KEY | TYPE | DESCRIPTION
Displayed | string | The text as displayed (including literals from the input mask).
Data | string | The data entered (not including literals from the input mask).

If the user presses the "Cancel" button on the dialog or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Dialog.Message

number Dialog.Message (

string Title,

string Text,

number Type = MB_OK,

number Icon = MB_ICONINFORMATION,

number DefaultButton = MB_DEFBUTTON1 )

Description

Presents a dialog to the user with an informative message on it.

Parameters

Title

(string) The text that will appear in the dialog title bar.

Text

(string) The text that will appear on the dialog.

Type

(number) The type of dialog to display:

CONSTANT | VALUE | DESCRIPTION
MB_OK | 0 | OK (Default)
MB_OKCANCEL | 1 | OK | Cancel
MB_ABORTRETRYIGNORE | 2 | Abort | Retry | Ignore
MB_YESNOCANCEL | 3 | Yes | No | Cancel
MB_YESNO | 4 | Yes | No
MB_RETRYCANCEL | 5 | Retry | Cancel

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question.
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information. (Default)

DefaultButton

(number) The button that will get the focus by default:

CONSTANT | VALUE | DESCRIPTION
MB_DEFBUTTON1 | 0 | The first button from the left. (Default)
MB_DEFBUTTON2 | 256 | The second button from the left.
MB_DEFBUTTON3 | 512 | The third button from the left.

Returns

(number) The numeric constant for the button that was pressed:

CONSTANT | VALUE | DESCRIPTION
IDOK | 1 | The OK button.
IDCANCEL | 2 | The Cancel button.
IDABORT | 3 | The Abort button.
IDRETRY | 4 | The Retry button.
IDIGNORE | 5 | The Ignore button.
IDYES | 6 | The Yes button.
IDNO | 7 | The No button.

If an error occurs, IDCANCEL (value 2) will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Dialog.PasswordInput

string Dialog.PasswordInput (

string Title,

string Prompt,

number Icon = MB_ICONNONE )

Description

Presents a "hidden input" dialog to collect a password from the user.

Note: Whatever the user types into this dialog will be hidden by asterisks, like this: *******

Parameters

Title

(string) The dialog title.

Prompt

(string) The text that will appear above the edit field.

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None. (Default)
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question.
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

Returns

(string) The text that was typed into the edit field if the OK button is pressed, or "CANCEL" if the Cancel button is pressed. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.SplashImage

Dialog.SplashImage (

string MediaFile,

number Time = 0,

boolean AllowClickToSkip = true )

Description

Displays a splash dialog containing an image.

Parameters

MediaFile

(string) The path to the image file. Click the browse button ( [image] ) to select a file.

Time

(number) The amount of time to display the dialog (in seconds).

AllowClickToSkip

(boolean) Whether the user can close the splash screen by clicking on it:

VALUE | DESCRIPTION
true | Allow the user to click on the dialog to close it. (Default)
false | Prevent the user from closing the dialog.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Dialog.TimedMessage

Dialog.TimedMessage (

string Title,

string Text,

number Time,

number Icon = MB_ICONINFORMATION )

Description

Presents a timed dialog to the user with an informative message on it.

Parameters

Title

(string) The text to be displayed on the title bar of the dialog.

Text

(string) The text to be displayed on the dialog.

Time

(number) The amount of time to make the dialog visible, in milliseconds.

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None.
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question.
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.AddImage

number DlgBillboard.AddImage (

number ControlID,

string FilePath,

number Position = -1 )

Description

Adds an image to a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

FilePath

(string) The path to the image file you want to add.

Note: The following image formats are supported in the billboard control: JPG, BMP, TIFF, GIF, PNG, PCX, and TGA. If you require alpha transparency, use 32-bit .PNG format.

Tip: You can use a hardcoded path or add images as primer files and reference them from _TempLaunchFolder.

Position

(number) The 1-based position to add the new image. Use -1 to add the image to the end of the control's image list.

Returns

(number) The 1-based position where the image was added. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


DlgBillboard.DeleteImage

DlgBillboard.DeleteImage (

number ControlID,

number Position )

Description

Deletes an image from a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Position

(number) The 1-based position of the image you want to remove from the control. Use -1 to remove all images.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.FillFromFolder

DlgBillboard.FillFromFolder (

number ControlID,

string FolderPath,

boolean EmptyFirst = false,

boolean Recurse = false )

Description

Fills a billboard control's images from a folder.

Parameters

ControlID

(number) The numeric ID of the billboard control.

FolderPath

(string) The folder containing images to add to the billboard control.

Note: The following image formats are looked for when adding images in the billboard control: JPG, BMP, TIFF, GIF, PNG, PCX, and TGA. If you require alpha transparency, use 32-bit .PNG format.

EmptyFirst

(boolean) Whether the billboard control should be emptied first:

VALUE | DESCRIPTION
true | Empty the billboard control before adding images.
false | Don't empty the billboard control. (Default)

Recurse

(boolean) Whether to recurse into subfolders when adding images:

VALUE | DESCRIPTION
true | Recurse into subfolders when adding images.
false | Don't recurse. Just add from the folder's root. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.GetCurrentImage

number DlgBillboard.GetCurrentImage (

number ControlID )

Description

Returns the index of the current image in a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Returns

(number) The 1-based index of the current image in the billboard control. If an error occurs, or there are no images in the control, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


DlgBillboard.GetImageCount

number DlgBillboard.GetImageCount (

number ControlID )

Description

Returns the number of images in a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Returns

(number) The number of images in the billboard control. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


DlgBillboard.GetImagePath

string DlgBillboard.GetImagePath (

number ControlID,

number Position )

Description

Gets the path to an image in a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Position

(number) The 1-based position of the image to get the path of.

Returns

(string) A string containing the path to the specified billboard image. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


DlgBillboard.GetPos

table DlgBillboard.GetPos (

number ControlID )

Description

Returns the X and Y screen coordinates of a billboard control in pixels. This coordinate refers to the upper left hand corner of the control's bounding box relative to the screen.

Note: The upper left hand corner of a screen has X and Y coordinates of 0.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Returns

(table) A table containing the control's current coordinates, indexed by values "X" and "Y". If the control cannot be found, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


DlgBillboard.GetProperties

table DlgBillboard.GetProperties (

number ControlID )

Description

Returns a table containing the properties of a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Returns

(table) A table containing the billboard control's properties, indexed by the following keys:

KEY

TYPE

DESCRIPTION

ImageFiles

table

A numerically indexed table containing the paths to the image files in the control.

BackgroundStyle

number

The style of the background defined by one of the following values:

CONSTANT | VALUE | DESCRIPTION
BG_SOLID | 0 | The background is the solid color defined in BackgroundColor.
BG_TRANSPARENT | 1 | The background is transparent.

BackgroundColor

number

The background color of the control.

BorderStyle

number

The border style defined by one of the following values:

CONSTANT | VALUE | DESCRIPTION
BORDER_NONE | 0 | The control contains no border.
BORDER_SOLID | 1 | The border is the solid color defined in BorderColor.

BorderColor

number

The border color of the control.

Interval

number

The duration each image is set to show (in milliseconds).

AutoStart

boolean

True if the billboard control is set to start automatically, false if it is not.

ResizeMode

number

The resize mode for the images defined by one of the following values:

CONSTANT | VALUE | DESCRIPTION
PROPORTIONAL | 0 | The image is resized so it fits inside the area defined by the control's bounding box. Tip: See NoEnlarge below.
STRETCH | 1 | The image is stretched to fill the entire area defined by the control's bounding box.
CROP | 2 | If the image dimensions are larger than the control's dimensions, the image will be cropped.

NoEnlarge

boolean

True if the image will be centered if it is smaller than the control dimensions when ResizeMode = PROPORTIONAL, false if it will be resized proportionally to fit the control.

Loop

boolean

True if the billboard control will begin playing from the beginning again whenever it reaches the end, or false if not.

Shuffle

boolean

True if the images will play in random order, false if they will play in the order defined at design-time.

Transitions

boolean

True if a transition effect will be shown between images, false if it will not.

Enabled

boolean

True if the billboard control is enabled, false if it is not.

Visible

boolean

True if the billboard control is visible, false if it is not.

X

number

The horizontal position (in pixels) of the top left corner of the control in relation to the current screen.

Note: The top left corner of the current screen has an X value of 0.

Y

number

The vertical position (in pixels) of the top left corner of the control in relation to the current screen.

Note: The top left corner of the current screen has a Y value of 0.

Width

number

The width (in pixels) of the billboard control.

Height

number

The height (in pixels) of the billboard control.

If the control cannot be found, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


DlgBillboard.GetSize

table DlgBillboard.GetSize (

number ControlID )

Description

Returns the pixel dimensions of a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Returns

(table) A table containing the control's pixel dimensions, indexed by values "Width" and "Height". If the control cannot be found, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


DlgBillboard.GoToImage

DlgBillboard.GoToImage (

number ControlID,

number Position )

Description

Navigate to a specific image in a billboard control.

Parameters

ControlID

(number The numeric ID of the billboard control.

Position

(number) The 1-based position of the image to navigate to.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.IsEnabled

boolean DlgBillboard.IsEnabled (

number ControlID )

Description

Returns true if a specific billboard control is enabled, or false if it's disabled.

Note: When a control is disabled, it doesn't respond to the user at all.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Returns

(boolean) True if the billboard control is enabled, false if it is disabled. If an error occurs, false will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


DlgBillboard.IsVisible

boolean DlgBillboard.IsVisible (

number ControlID )

Description

Returns true if a specific billboard control is visible, and false if it isn't.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Returns

(boolean) True if the billboard control is visible, false if it's invisible. If an error occurs, false will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


DlgBillboard.Navigate

DlgBillboard.Navigate (

number ControlID,

number NavigateType )

Description

Navigates to an image in a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

NavigateType

(number) The type of navigation to perform. Choose from one of the following values:

CONSTANT | VALUE | DESCRIPTION
BILLBOARD_FIRST | 0 | Navigate to the first image.
BILLBOARD_LAST | 1 | Navigate to the last image.
BILLBOARD_NEXT | 2 | Navigate to the next image.
BILLBOARD_PREV | 3 | Navigate to the previous image.
BILLBOARD_RANDOM | 4 | Navigate to a random image.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.Pause

DlgBillboard.Pause (

number ControlID )

Description

Pauses a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.Play

DlgBillboard.Play (

number ControlID )

Description

Plays a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.SetEnabled

DlgBillboard.SetEnabled (

number ControlID,

boolean Enabled = true )

Description

Sets the enabled/disabled state of a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Enabled

(boolean) Whether to make the billboard control enabled or disabled:

VALUE | DESCRIPTION
true | Enabled. (Default)
false | Disabled.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.SetPos

DlgBillboard.SetPos (

number ControlID,

number X,

number Y )

Description

Sets the X and Y pixel coordinates of a billboard control relative to the screen.

Parameters

ControlID

(string) The numeric ID of the billboard control.

X

(number) The new X pixel coordinate (horizontal position) to set for the billboard control. This is the X coordinate of the upper left hand corner of the control's bounding box relative to the current screen.

Y

(number) The new Y pixel coordinate (vertical position) to set for the billboard control. This is the Y coordinate of the upper left hand corner of the control's bounding box relative to the current screen.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.SetProperties

DlgBillboard.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a billboard control on the current screen.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Properties

(table) A table containing the billboard control's properties indexed by the following keys:

KEY

TYPE

DESCRIPTION

ImageFiles

table

A numerically indexed table containing the paths to the image files to use in the billboard control. Any existing images in the control will be cleared before adding these.

BackgroundStyle

number

The style of the background to use, defined by one of the following values:

CONSTANT | VALUE | DESCRIPTION
BG_SOLID | 0 | Use a solid background defined by the color in BackgroundColor.
BG_TRANSPARENT | 1 | Set the background as transparent.

BackgroundColor

number

The background color to use in the control.

BorderStyle

number

The border style to use defined by one of the following values:

CONSTANT | VALUE | DESCRIPTION
BORDER_NONE | 0 | Don't set any border.
BORDER_SOLID | 1 | Use a solid color as the border defined by the color in BorderColor.

BorderColor

number

The border color to use in the control.

Interval

number

The duration to show each image (in milliseconds).

AutoStart

boolean

True to have the billboard control start automatically, false to not.

ResizeMode

number

The resize mode to use for the images defined by one of the following values:

CONSTANT | VALUE | DESCRIPTION
PROPORTIONAL | 0 | Resize the image so it fits inside the area defined by the control's bounding box. Tip: See the NoEnlarge setting below.
STRETCH | 1 | Stretch the image to fill the entire area defined by the control's bounding box.
CROP | 2 | If the image dimensions are larger than the control's dimensions, crop the image.

NoEnlarge

boolean

True to center the image if it is smaller than the control dimensions when ResizeMode = PROPORTIONAL, false to resize it proportionally to fit the control.

Loop

boolean

True if the billboard control should begin playing from the beginning again whenever it reaches the end, or false if it should not.

Shuffle

boolean

True if the images should play in random order, false if they should play in the order defined at design-time.

Transitions

boolean

True if a transition effect should be shown between images, false if it should not.

Enabled

boolean

True if the billboard control should be enabled, false if it should not be.

Visible

boolean

True if the billboard control should be visible, false if it should not be.

X

number

The horizontal position (in pixels) of the top left corner of the billboard control in relation to the current screen.

Note: The top left corner of the current screen has an X value of 0.

Y

number

The vertical position (in pixels) of the top left corner of the billboard control in relation to the current screen.

Note: The top left corner of the current screen has a Y value of 0.

Width

number

The width (in pixels) of the control.

Height

number

The height (in pixels) of the control.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.SetSize

DlgBillboard.SetSize (

number ControlID,

number Width,

number Height )

Description

Sets the size of a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Width

(number) The new width of the billboard control in pixels.

Height

(number) The new height of the billboard control in pixels.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgBillboard.SetVisible

DlgBillboard.SetVisible (

number ControlID,

boolean Visible = true )

Description

Sets the visibility of a billboard control.

Parameters

ControlID

(number) The numeric ID of the billboard control.

Visible

(boolean) Whether to make the billboard control visible or invisible:

VALUE | DESCRIPTION
true | Visible. (Default)
false | Invisible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgButton.GetProperties

table DlgButton.GetProperties (

number ControlID )

Description

Gets the properties of a button control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the button control whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Whether or not the control is enabled. If true is returned the control is enabled. A false result means it is disabled. You can access this value using tb.Enabled.
Text | string | The text currently displayed in the control. It can be accessed using tb.Text.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgButton.SetProperties

DlgButton.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a button control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the button control whose properties you want to set.

Properties

(table) A table containing the button control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Enable or disable the control. Setting Enabled to true will enable the control and false will disable it. For example, tb.Enabled = true or {Enabled=true}.
Text | string | The text you want to appear in the control. For example, tb.Text = "Sample Text" or {Text="Sample Text"}.
Visible | boolean | Sets the visibility of the control. Setting it to true means the control will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgCheckBox.GetProperties

table DlgCheckBox.GetProperties (

number ControlID )

Description

Gets the properties of a check box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the check box control whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Checked | boolean | Whether or not the check box is selected. You can access this value using tb.Checked.
Enabled | boolean | Whether or not the control is enabled. If true is returned the control is enabled. A false result means it is disabled. You can access this value using tb.Enabled.
Text | string | The text currently displayed in the control. It can be accessed using tb.Text.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgCheckBox.SetProperties

DlgCheckBox.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a check box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the check box control whose properties you want to set.

Properties

(table) A table containing the check box control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Checked | boolean | Select or unselect the check box. Setting Checked to true will select the check box and false will unselect it. For example, tb.Checked = true or {Checked=true}.
Enabled | boolean | Enable or disable the control. Setting Enabled to true will enable the control and false will disable it. For example, tb.Enabled = true or {Enabled=true}.
Text | string | The text you want to appear in the control. For example, tb.Text = "Sample Text" or {Text="Sample Text"}.
Visible | boolean | Sets the visibility of the control. Setting it to true means the control will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgComboBox.AddItem

number DlgComboBox.AddItem (

number ControlID,

string ItemText )

Description

Adds an item to a combo box control. If the combo box is sorted, the item will be added in sorted order, otherwise it will be added to the end.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the combo box control that you want to add an item to.

ItemText

(string) The text of the item you want to add.

Returns

(number) The index (line number) where the item was added. If an error occurs, -1 is returned. If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgComboBox.GetItemData

string DlgComboBox.GetItemData (

number ControlID,

number Index )

Description

Gets the associated data string of an item in a combo box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the combo box control whose item data you want.

Index

(number) The index (line number) of the combo box item whose data you want. The first item in the list has an index of 1.

Returns

(string) The associated data string of the specified combo box item. If the item does not contain any data, a blank string "" is returned.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgComboBox.GetItemText

string DlgComboBox.GetItemText (

number ControlID,

number Index )

Description

Returns the text of an item in a combo box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the combo box control whose item text you want.

Index

(number) The index (line number) of the combo box item whose text you want. The first item in the list has an index of 1.

Returns

(string) The text of the specified combo box item.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgComboBox.GetProperties

table DlgComboBox.GetProperties (

number ControlID )

Description

Gets the properties of a combo box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the combo box control whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Whether or not the control is enabled. If true is returned the control is enabled. A false result means it is disabled. You can access this value using tb.Enabled.
ItemCount | number | The number of items currently in the combo box. You can access this value using tb.ItemCount.
Selected | number | The one based index of the currently selected item. If nothing is selected, -1 is returned. It can be access using tb.Selected.
Sorted | boolean | Whether or not the combo box is sorted. If true is returned, it is sorted and a false result means it is not sorted. You can access this value using tb.Sorted.
Text | string | The text currently displayed in the control. It can be accessed using tb.Text.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgComboBox.InsertItem

number DlgComboBox.InsertItem (

number ControlID,

number Index,

string ItemText )

Description

Inserts an item into a combo box control.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the combo box control you want to insert the item into.

Index

(number) The index (line number) to insert the new item. Use an index of -1 to insert at the end of the list.

ItemText

(string) The item text to display for the new item.

Returns

(number) The index (line number) where the item was inserted. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgComboBox.RemoveItem

DlgComboBox.RemoveItem (

number ControlID,

number Index )

Description

Removes an item from a combo box control.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the combo box control you want to remove an item from.

Index

(number) The index (line number) of the item to remove from the combo box. The first item in the list has an index of 1. You can use an index of -1 to remove all items from the list.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgComboBox.SetItemData

DlgComboBox.SetItemData (

number ControlID,

number Index,

string ItemData )

Description

Sets a combo box control's item data on the current screen to a string that can later be retrieved using a DlgComboBox.GetItemData action.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the combo box control whose item data you want to set.

Index

(number) The index (line number) of the combo box item whose data you want to set. The first item in the list has an index of 1.

ItemData

(string) The text you want to set the item's associated data to.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgComboBox.SetProperties

DlgComboBox.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a combo box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the combo box control whose properties you want to set.

Properties

(table) A table containing the combo box control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Enable or disable the control. Setting Enabled to true will enable the control and false will disable it. For example, tb.Enabled = true or {Enabled=true}.
Selected | number | The one based index of the combo box item you want to select. You can use -1 to deselect all items. For example, tb.Selected = 2 or {Selected=2}.
Sorted | boolean | Sort the control alphabetically. Setting Sorted to true will sort the items and false will not. For example, tb.Sorted = true or {Sorted=true}.
Text | string | The text you want to appear in the control. For example, tb.Text = "Sample Text" or {Text="Sample Text"}.
Visible | boolean | Sets the visibility of the control. Setting it to true means the control will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgEditField.GetProperties

table DlgEditField.GetProperties (

number ControlID )

Description

Gets the properties of an edit field control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the edit field control whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Whether or not the control is enabled. If true is returned the control is enabled. A false result means it is disabled. You can access this value using tb.Enabled.
Text | string | The text currently displayed in the control. It can be accessed using tb.Text.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.
Multiline | boolean | Whether or not the control supports multiple lines of text. If true is returned, multiline text is enabled. A false result means it is disabled. You can access this value using tb.Multiline. This option only has an effect if the control is on a custom screen.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgEditField.SetProperties

DlgEditField.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of an edit field control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the edit field control whose properties you want to set.

Properties

(table) A table containing the edit field control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Enable or disable the control. Setting Enabled to true will enable the control and false will disable it. For example, tb.Enabled = true or {Enabled=true}.
Text | string | The text you want to appear in the control. For example, tb.Text = "Sample Text" or {Text="Sample Text"}.
Visible | boolean | Sets the visibility of the control. Setting it to true means the control will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.
Multiline | boolean | Whether multiline text support is enabled or disabled. Setting Multiline to true will enable multiline text in the control, while setting it to false will disable it. For example, tb.Multiline=true or {Multiline=true}. This option only has an effect if this control is on a custom screen.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgGroupBox.GetProperties

table DlgGroupBox.GetProperties (

number ControlID )

Description

Gets the properties of a group box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the group box control whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Whether or not the control is enabled. If true is returned the control is enabled. A false result means it is disabled. You can access this value using tb.Enabled.
Text | string | The text currently displayed in the control. It can be accessed using tb.Text.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgGroupBox.SetProperties

DlgGroupBox.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a group box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the group box control whose properties you want to set.

Properties

(table) A table containing the group box control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Enable or disable the control. Setting Enabled to true will enable the control and false will disable it. For example, tb.Enabled = true or {Enabled=true}.
Text | string | The text you want to appear in the control. For example, tb.Text = "Sample Text" or {Text="Sample Text"}.
Visible | boolean | Sets the visibility of the control. Setting it to true means the control will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgListBox.AddItem

number DlgListBox.AddItem (

number ControlID,

string Text )

Description

Adds an item to a list box control. If the list box is sorted, the item is added at the sorted position, otherwise it is added to the end.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control you want to add an item to.

Text

(string) The text of the item you want to add.

Returns

(number) The 1-based index where the item was added. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgListBox.DeleteItem

number DlgListBox.DeleteItem (

number ControlID,

number Index )

Description

Deletes an item from a list box control.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control you want to remove an item from.

Index

(number) The index (line number) of the item to delete from the list box. The first item in the list has an index of 1. You can use an index of -1 to delete all items from the list.

Returns

(number) The number of items in the list box after the item is deleted. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgListBox.FindItem

number DlgListBox.FindItem (

number ControlID,

number StartAfter,

string SearchText )

Description

Finds an item in a list box control based on a search string and returns its index.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control that you want to search.

StartAfter

(number) The index (line number) to start searching after. The search will begin in the next item in the list. You can use an index of -1 to search all list box items. The first list box item has an index of 1.

SearchText

(string) The string of text to search for in the list box control. You can use the * and ? wildcards in this field to search for text that matches a specific pattern.

Returns

(number) The first item index where the search string was found. If the string was not found or an error occurs, the value -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgListBox.GetCount

number DlgListBox.GetCount (

number ControlID )

Description

Returns the number of items in a list box control.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control whose number of items you want.

Returns

(number) The number of items in the specified list box control. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgListBox.GetItemProperties

table DlgListBox.GetItemProperties (

number ControlID,

number Index )

Description

Gets the properties of an item in a list box control given its index.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control whose item properties you want.

Index

(number) The index of the item whose properties you want. The first item in the list has an index of 1. You can use -1 to get the properties of the last item in the list.

Returns

(table) A table containing the list box item's properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Checked | boolean | Whether or not the list box item is "checked." This key is only valid if the list box is using the Checklist Box style. If true is returned the item is checked. A false result means it is not checked, or the list box is not using the Checklist Box style. You can access this value using tb.Checked.
ItemData | string | The list box item's associated data string. You can access this value using tb.ItemData.
Selected | boolean | Whether or not the item is currently selected. If true is returned, the item is selected and if false is returned, it is not. You can access this value using tb.Selected.
Text | string | The list box item's text. You can access this value using tb.Text.

If the current screen does not contain the control or item, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgListBox.GetProperties

table DlgListBox.GetProperties (

number ControlID )

Description

Gets the properties of a list box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Whether or not the control is enabled. If true is returned the control is enabled. A false result means it is disabled. You can access this value using tb.Enabled.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgListBox.GetSelected

table DlgListBox.GetSelected (

number ControlID )

Description

Returns a numerically indexed table containing the indexes (line numbers) of all of the selected items in a specified list box control.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control whose selected items you want.

Returns

(table) A numerically indexed table containing all item indexes that are currently selected. If no items are selected or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgListBox.GetSelectedCount

number DlgListBox.GetSelectedCount (

number ControlID )

Description

Returns the number of items that are selected in a list box control.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control whose number of selected items you want.

Returns

(number) The number of items that are selected in the specified list box control. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgListBox.InsertItem

number DlgListBox.InsertItem (

number ControlID,

number Index,

string Text )

Description

Inserts an item into a list box control at the specified position.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control that you want to insert an item into.

Index

(number) The position you want to insert the item into. The first item in the list has the index 1. To insert the item at the end of the list you can use the index -1.

Text

(string) The text of the item being inserted.

Returns

(number) The position of the inserted item. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgListBox.SetItemProperties

DlgListBox.SetItemProperties (

number ControlID,

number Index,

table Properties )

Description

Sets the properties of an item in a list box control given its index.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control whose item properties you want to set.

Index

(number) The index of the item whose properties you want to set. The first item in the list has an index of 1. You can use -1 to set the properties of the last item in the list.

Properties

(table) A table containing the list box item's properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Checked | boolean | Whether or not to "check" the list box item. This key is only valid if the list box is using the Checklist Box style. If set to true, the item is checked, and if set to false, the item is unchecked. You can set this value using tb.Checked=true, or {Checked=true}.
ItemData | string | The associated data string to set for the item. You can set this value using tb.ItemData="New Item Data" or {ItemData="New Item Data."
Selected | boolean | Whether or not to select the list box item. If set to true, the item is selected and if set to false, it is deselected. You can set this value using tb.Selected=true or {Selected=true}.
Text | string | The new text you want to set for list box item. You can set this value using tb.Text = "New Text", or {Text="New Text"}.

Note: All changes will be made immediately (based on the update state from DlgListBox.SetUpdate) and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgListBox.SetProperties

DlgListBox.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a list box control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control whose properties you want to set.

Properties

(table) A table containing the list box control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Enable or disable the control. Setting Enabled to true will enable the control and false will disable it. For example, tb.Enabled = true or {Enabled=true}.
Visible | boolean | Sets the visibility of the control. Setting it to true means the control will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgListBox.SetUpdate

DlgListBox.SetUpdate (

number ControlID,

boolean Update = true )

Description

Sets the update state of a list box control. The update state controls whether or not the list box will be redrawn to reflect any changes that have been made. When a list box control's update state is set to false, any actions to modify it will not be visible to the user until this action is called to enable the update state (set to true).

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the list box control whose update state you want to set.

Update

(boolean) Whether to update (redraw) the list box control:

VALUE | DESCRIPTION
true | Redraw the list box to reflect any changes. (Default)
false | Do not redraw the list box, even if there are changes.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgProgressBar.GetPos

number DlgProgressBar.GetPos (

number ControlID )

Description

Returns the current position of the progress meter within the progress bar control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the progress bar control whose position you want.

Returns

(number) The current position of the progress meter within the progress bar. If an error occurs -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgProgressBar.GetProperties

table DlgProgressBar.GetProperties (

number ControlID )

Description

Returns a table containing the properties of a progress bar control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the progress bar whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Whether or not the control is enabled. If true is returned the control is enabled. A false result means it is disabled. You can access this value using tb.Enabled.
Text | string | The text currently displayed in the progress meter. It can be accessed using tb.Text.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgProgressBar.GetRange

table DlgProgressBar.GetRange (

number ControlID )

Description

Returns a table containing the range of the progress bar control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the progress bar whose range you want.

Returns

(table) A table containing the control range values indexed by the following categories:

KEY | TYPE | DESCRIPTION
Begin | number | The beginning of the progress meter range. You can access this value using tb.Begin.
End | number | The end of the progress meter range. You can access this value using tb.End.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgProgressBar.SetPos

DlgProgressBar.SetPos (

number ControlID,

number Pos )

Description

Sets the position of the progress meter within the progress bar control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the progress bar control whose position you want to set.

Pos

(number) The position you want to set the progress meter to. This position should be a value within the range defined in DlgProgressBar.SetRange.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgProgressBar.SetProperties

DlgProgressBar.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a progress bar control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the progress bar control whose properties you wan to set.

Properties

(table) A table containing the progress bar control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Enable or disable the control. Setting Enabled to true will enable the control and false will disable it. For example, tb.Enabled = true or {Enabled=true}.
Text | string | The text you want to appear in the control. For example, tb.Text = "Sample Text" or {Text="Sample Text"}.
Visible | boolean | Sets the visibility of the control. Setting it to true means the control will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgProgressBar.SetRange

DlgProgressBar.SetRange (

number ControlID,

number Begin,

number End )

Description

Sets the range of a progress bar control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the progress bar control whose range you want to set.

Begin

(number) The beginning value of the range. This value must be greater than or equal to -32767.

End

(number) The ending value of the range. This value must be less than or equal to 32767.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgProgressBar.SetStep

DlgProgressBar.SetStep (

number ControlID,

number Step )

Description

Sets the step value of the progress bar control that will be used whenever DlgProgressBar.Step is called.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the progress bar control whose step value you want to set.

Step

(number) The numeric step value you want to use.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgProgressBar.Step

DlgProgressBar.Step (

number ControlID )

Description

Increments the current progress in a progress bar control by the step amount specified in the DlgProgressBar.SetStep action.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the progress bar control whose progress you want to increment.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgRadioButton.GetProperties

table DlgRadioButton.GetProperties (

number ControlID )

Description

Gets the properties of a radio button control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the radio button control whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Checked | boolean | Whether or not the radio button is selected. You can access this value using tb.Checked.
Enabled | boolean | Whether or not the control is enabled. If true is returned the control is enabled. A false result means it is disabled. You can access this value using tb.Enabled.
Text | string | The text currently displayed in the control. It can be accessed using tb.Text.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgRadioButton.SetProperties

DlgRadioButton.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a radio button control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the radio button control whose properties you want to set.

Properties

(table) A table containing the radio button control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Checked | boolean | Select or unselect the radio button. Setting Checked to true will select the radio button and false will unselect it. For example, tb.Checked = true or {Checked=true}.
Enabled | boolean | Enable or disable the control. Setting Enabled to true will enable the control and false will disable it. For example, tb.Enabled = true or {Enabled=true}.
Text | string | The text you want to appear in the control. For example, tb.Text = "Sample Text" or {Text="Sample Text"}.
Visible | boolean | Sets the visibility of the control. Setting it to true means the control will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgScrollingText.AppendLine

DlgScrollingText.AppendLine (

number ControlID,

string Line = "",

boolean AddNewLine = true,

boolean ScrollToEnd = true )

Description

Appends a new line to the current text in a scrolling text control.

Note: This action only works when the Scrolling Text control is in Text mode.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the scrolling text control that you want to add a new line to.

Line

(string) The line of text you want to add.

AddNewLine

(boolean) Whether to add the text on a new line in the scrolling text window:

VALUE | DESCRIPTION
true | Add the text on a new line. (Default)
false | Append the new text to the last line.

ScrollToEnd

(boolean) Whether to scroll to the end of the text window after the text has been added:

VALUE | DESCRIPTION
true | Scroll to the end. (Default)
false | Keep the text window at its current position.

Returns

Nothing. If the current screen does not contain the control, this action will fail. You can use Application.GetLastError to determine whether this action failed, and why.


DlgScrollingText.GetProperties

table DlgScrollingText.GetProperties (

number ControlID )

Description

Gets the properties of a scrolling text control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the scrolling text control whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Whether or not the control is enabled. If true is returned the control is enabled. A false result means it is disabled. You can access this value using tb.Enabled.
Mode | number | The text mode currently being used. If 1 is returned, plain text is being used. If 2 is returned, HTML is being used.
Text | string | The text currently displayed in the control. It can be accessed using tb.Text.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgScrollingText.SetProperties

DlgScrollingText.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a scrolling text control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the scrolling text control whose properties you want to set.

Properties

(table) A table containing the scrolling text control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Enabled | boolean | Enable or disable the control. Setting Enabled to true will enable the control and false will disable it. For example, tb.Enabled = true or {Enabled=true}. Note: This option is only supported for plain text mode.
Mode | number | The text mode you want to use. For plain text use 1 (tb.Mode = 1). For HTML, use 2 (tb.Mode = 2).
Text | string | The text you want to appear in the control. For example, tb.Text = "Sample Text" or {Text="Sample Text"}.
Visible | boolean | Sets the visibility of the control. Setting it to true means the control will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DlgSelectPackages.GetCategoryProperties

table DlgSelectPackages.GetCategoryProperties (

number PackageControlID,

number CategoryControlID )

Description

Gets the properties of a package category within the select package control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen. This action is normally used on the Select Packages screen.

Tip: You can also get and set the properties of packages using SetupData.GetPackageProperties and SetupData.SetPackageProperties and get a list of the packages using SetupData.GetPackageList.

Parameters

PackageControlID

(number) The numeric ID of the select packages control whose category properties you want.

CategoryControlID

(number) The numeric ID of the package category whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Text | string | The text currently displayed in the category. It can be accessed using tb.Text.
Description | string | The description text of category. It can be accessed using tb.Description.
Enabled | boolean | Whether or not the category is enabled. It can be accessed using tb.Enabled.
Expanded | boolean | Whether or not the category is expanded in the tree view. It can be accessed using tb.Expanded.
State | number | The current state of the category. One of the following states (constant or corresponding value) are returned: CB_UNCHECKED = 1 (the category is currently unchecked) CB_CHECKED = 2 (the category is currently checked) CB_INDETERMINATE = 3 (the category contains subcategories with mixed states) It can be accessed using tb.State.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgSelectPackages.SetCategoryProperties

DlgSelectPackages.SetCategoryProperties (

number PackageControlID,

number CategoryControlID,

table Properties )

Description

Sets the properties of a package category within the select package control on the current screen.

Note: This action will not cause the select packages tree to redraw unless you call the DlgSelectPackages.UpdateDisplay action.

This action will only work if called from a screen's events and if the named control is on the current screen. This action is normally used on the Select Packages screen.

Tip: You can also get and set the properties of packages using SetupData.GetPackageProperties and SetupData.SetPackageProperties and get a list of the packages using SetupData.GetPackageList.

Parameters

PackageControlID

(number) The numeric ID of the select packages control whose category properties you want to set.

CategoryControlID

(number) The numeric ID of the package category whose properties you want to set.

Properties

(table) A table containing the control properties you want to set, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Text | string | The text you want to display in the category. This value can be assigned to tb.Text.
Description | string | The description text you want to display for the category. This value can be assigned to tb.Description.
Enabled | boolean | Whether to enable the category. Setting tb.Enabled to true enables the category and setting tb.Enabled to false disables the category.
Expanded | boolean | Whether to expand the category in the tree view. Setting tb.Expanded to true expands the category and setting tb.Expanded to false collapses the category tree.
State | number | The state to set the category to. The following states are available (constant followed by its value): CB_UNCHECKED = 1 (deselect the category) CB_CHECKED = 2 (select the category) This value can be assigned using the format tb.State = CB_CHECKED or {State=CB_CHECKED}

Returns

Nothing. If the current screen does not contain the control, this action will fail. You can use Application.GetLastError to determine whether this action failed, and why.


DlgSelectPackages.UpdateDisplay

DlgSelectPackages.UpdateDisplay (

number ControlID )

Description

Updates the currently displayed package list based upon the current internal data.

Note: This action will only work if called from a screen's events and if the named control is on the current screen. This action is normally used on the Select Packages screen.

Parameters

ControlID

(number) The numeric ID of the select packages control whose display you want to update.

Returns

Nothing. If the current screen does not contain the control, this action will fail. You can use Application.GetLastError to determine whether this action failed, and why.


DlgStaticText.GetProperties

table DlgStaticText.GetProperties (

number ControlID )

Description

Gets the properties of a static text control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the static text control whose properties you want.

Returns

(table) A table containing the control properties, indexed by the following categories:

KEY | TYPE | DESCRIPTION
Text | string | The text currently displayed in the control. It can be accessed using tb.Text.
Visible | boolean | Whether or not the control is visible. If true is returned the control is visible. A false result means it is not visible. You can access this value using tb.Visible.

If the current screen does not contain the control, this action will fail. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


DlgStaticText.SetProperties

DlgStaticText.SetProperties (

number ControlID,

table Properties )

Description

Sets the properties of a static text control on the current screen.

Note: This action will only work if called from a screen's events and if the named control is on the current screen.

Parameters

ControlID

(number) The numeric ID of the static text control whose properties you want to set.

Properties

(table) A table containing the static text control properties indexed by the following keys:

KEY | TYPE | DESCRIPTION
Text | string | The static text you want to appear in the control. For example, tb.Text="Sample Text" or {Text="Sample Text"}.
Visible | boolean | Sets the visibility of the static text control. True means it will be visible and false means it will be invisible. For example, tb.Visible=true or {Visible=true}.

Note: All changes will be made immediately and only the properties that you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


DLL.CallFunction

string DLL.CallFunction (

string Filename,

string FunctionName,

string Parameters = "",

number ReturnType = 0,

number CallConvention = 0 )

Description

Calls a function in a dynamically linked library (DLL). It can be used to extend Setup Factory's functionality with your own functions.

Warning: Calling DLLs is a fairly advanced thing to do and writing DLLs is best done with C or C++. We have tried to provide a large range of functionality with Setup Factory, so there aren't many reasons to use external DLL calls. Make sure that you know exactly what parameters the DLL function you are calling takes. Providing too many or not enough parameters can corrupt the application's memory so please do so at your own risk.

Parameters

Filename

(string) The path to the DLL file.

FunctionName

(string) The name of the function within the DLL.

Parameters

(string) The comma-separated list of parameters that you want to pass to the function.

Note: Place double-quotes around any parameters that you want passed as NULL-terminated string pointers. Only ANSI strings are supported, not Unicode. Parameters without quotes are passed as LONG integers.

If any parameters are strings, you need to escape the double quotes of the parameters. For example, if your parameter is "String 1" and the number 2, your parameter string would be: "\"String1\", 2"

All parameters are one-way only - they can be passed into the DLL function, but they cannot be evaluated after the function has been called. (In other words, these parameters are pass-by-value, not pass-by-reference.)

ReturnType

(number) The type of value returned from the function:

CONSTANT | VALUE | DESCRIPTION
DLL_RETURN_TYPE_INTEGER | 0 | Setup Factory will interpret the function's return value as a 16-bit integer (int).
DLL_RETURN_TYPE_LONG | 1 | Setup Factory will interpret the function's return value as a 32-bit integer (long).
DLL_RETURN_TYPE_STRING | 2 | Setup Factory will interpret the function's return value as a NULL-terminated string.

Note: If the function doesn't return a value (the function returns void), use DLL_RETURN_TYPE_LONG.

CallConvention

(number) The calling convention that Setup Factory will use when calling the DLL function:

CONSTANT | VALUE | DESCRIPTION
DLL_CALL_CDECL | 0 | Call the DLL function using the __cdecl calling convention.
DLL_CALL_STDCALL | 1 | Call the DLL function using the __stdcall calling convention.

Returns

(string) The value that was returned from the DLL function as a result of the function call. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Drive.Eject

Drive.Eject (

string Drive )

Description

Ejects a CD or DVD-ROM drive when given a valid drive letter.

Parameters

Drive

(string) The drive to eject. The first character of the string will be the drive letter used. Therefore "E", "E:"," E:\" and "E:\Myfile.txt" are all valid values if you want to eject the E: drive.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Drive.Enumerate

table Drive.Enumerate (

)

Description

Returns a numerically indexed table containing all of the drives on the user's system.

Parameters

None.

Returns

(table) A numerically indexed table containing the drive letters of all of the drives on the user's system. The stored values will be in a format such as A:\. If an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Drive.GetFreeSpace

number Drive.GetFreeSpace (

string Drive )

Description

Gets the amount of free disk space of a specific drive and returns it's numeric size in Megabytes.

Parameters

Drive

(string) The drive to query for disk space. The first character of the string will be the drive letter used. Therefore "C", "C:"," C:\" and "C:\Myfile.txt" are all valid Drive values.

Returns

(number) The amount of free disk space in Megabytes. If the specified drive is not valid or any other error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Drive.GetInformation

table Drive.GetInformation (

string Drive )

Description

Returns a table of information about a given drive.

Parameters

Drive

(string) The drive whose information you want. The drive must be in the format "C:" or "C:\".

Returns

(table) A table containing the specified drive's information, indexed by the following keys:

KEY | TYPE | DESCRIPTION
Label | string | The volume label of the drive. You can access this value using tb.Label.
FileSystem | string | The type of file system on the drive. For example, "FAT32", "NTFS", etc. You can access this value using tb.FileSystem.
SerialNumber | number | The drive's serial number. You can access this value using tb.SerialNumber.
DisplayName | string | The description of the drive as it appears in Windows Explorer's My Computer view. You can access this value using tb.DisplayName.

If an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Drive.GetSize

number Drive.GetSize (

string Drive )

Description

Gets the disk size of a specific hard drive and returns it's numeric size in Megabytes.

Parameters

Drive

(string) The drive whose size you want. The first character of the string will be the drive letter used. Therefore "C", "C:"," C:\" and "C:\Myfile.txt" are all valid Drive values.

Returns

(number) The size of the drive in Megabytes. If the specified drive is not valid or any other error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Drive.GetType

number Drive.GetType (

string Drive )

Description

Gets the type of a specific drive.

Parameters

Drive

(string) The drive whose type you want. The first character of the string will be the drive letter used. Therefore "C", "C:"," C:\" and "C:\Myfile.txt" are all valid Drive values.

Returns

(number) The type of drive detected:

CONSTANT | VALUE | DESCRIPTION
DRIVE_UNKNOWN | 0 | The type cannot be determined.
DRIVE_NO_ROOT_DIR | 1 | The drive is either invalid or the drive does not exist.
DRIVE_REMOVABLE | 2 | The drive is a removable drive.
DRIVE_FIXED | 3 | The drive is a non-removable (fixed) drive.
DRIVE_REMOTE | 4 | The drive is a remote network drive.
DRIVE_CDROM | 5 | The drive is a CD-ROM or DVD-ROM drive.
DRIVE_RAMDISK | 6 | The drive is a RAM disk.

If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Drive.GetUsedSpace

number Drive.GetUsedSpace (

string Drive )

Description

Gets the amount of used disk space of a specific drive and returns it's numeric size in Megabytes.

Parameters

Drive

(string) The drive to query for used disk space. The first character of the string will be the drive letter used. Therefore "C", "C:"," C:\" and "C:\Myfile.txt" are all valid Drive values.

Returns

(number) The amount of used disk space in Megabytes. If the specified drive is not valid or any other error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.Copy

File.Copy (

string Source,

string Destination,

boolean Recurse = true,

boolean Overwrite = true,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Description

Copies a file to another location.

Parameters

Source

(string) The path to the file that you want to copy. You can use the * and ? wildcards in this field to copy multiple files.

Destination

(string) The path to the destination folder or file that you want to copy to.

Warning: Any folders in the destination path must already exist when performing this action, or an error will result.

Tip: You can use a Folder.Create action to create a destination folder if necessary.

Recurse

(boolean) Whether to recurse through subfolders when a wildcard is used in the Source parameter:

VALUE | DESCRIPTION
true | Recurse. (Default)
false | Don't recurse.

Overwrite

(boolean) Whether to overwrite any files in the destination folder if they have the same names as the files being copied:

VALUE | DESCRIPTION
true | Copy the source files right over the destination files. (Default)
false | Don't copy a file if another file with the same name already exists in the destination folder.

AbortOnFail

(boolean) Whether to abort the copy operation if an error occurs:

VALUE | DESCRIPTION
true | Stop copying as soon as the first error occurs.
false | Continue copying files even if some files fail to copy. (Default)

IncludeHiddenFiles

(boolean) Whether to copy files that have the "hidden" or "system" attributes set:

VALUE | DESCRIPTION
true | Copy files even if they have the "hidden" or "system" attributes set.
false | Don't copy any files that have the "hidden" or "system" attributes set. (Default)

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the copy operation. (You can use this callback function to display the progress of the copy operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being copied.

Destination

(string) The destination path for file being copied.

Copied

(number) The number of bytes copied so far.

Total

(number) The total bytes that will be copied.

FileCopied

(number) The number of bytes of the current file copied so far.

FileTotal

(number) The current file's total bytes that will be copied.

The callback function should return a boolean value (true or false) indicating whether the copy operation should continue:

VALUE | DESCRIPTION
true | Continue with the copy operation.
false | Stop the copy operation as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Delete

File.Delete (

string Source,

boolean Recurse = false,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Description

Deletes a file.

Parameters

Source

(string) The path to the file that you want to delete. You can use the * and ? wildcards in this field to delete multiple files.

Recurse

(boolean) Whether to recurse through subfolders when a wildcard is used in the Source parameter:

VALUE | DESCRIPTION
true | Recurse. (Default)
false | Don't recurse.

AbortOnFail

(boolean) Whether to abort the delete operation if an error occurs:

VALUE | DESCRIPTION
true | Stop deleting as soon as the first error occurs.
false | Continue deleting files even if some files fail to be deleted. (Default)

IncludeHiddenFiles

(boolean) Whether to delete files that have the "hidden" or "system" attributes set:

VALUE | DESCRIPTION
true | Delete files even if they have the "hidden" or "system" attributes set.
false | Don't delete any files that have the "hidden" or "system" attributes set. (Default)

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the delete operation. (You can use this callback function to display the progress of the delete operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being deleted.

Deleted

(number) The number of bytes deleted so far.

Total

(number) The total bytes that will be deleted.

The callback function should return a boolean value (true or false) indicating whether the delete operation should continue:

VALUE | DESCRIPTION
true | Continue with the delete operation.
false | Stop the delete operation as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.DeleteOnReboot

File.DeleteOnReboot (

string Filename )

Description

Deletes a file on the next system reboot.

Parameters

Filename

(string) The path to the file to delete on the next reboot.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.DoesExist

boolean File.DoesExist (

string Filename )

Description

Returns true if a file exists at a specific location or false if it does not.

Parameters

Filename

(string) The path to the file.

Returns

(boolean) True if the file exists at the specified location, false if it doesn't or if an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.ExploreFolder

File.ExploreFolder (

string Path,

number WindowMode = SW_SHOWNORMAL )

Description

Explores a folder on the user's system.

Note: This is the same as right-clicking on a folder in Windows and choosing Explore.

Parameters

Path

(string) The path to the folder that will be explored.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Find

table File.Find (

string Folder,

string Filename,

boolean Recurse = false,

boolean IncludeFolders = false,

function CallbackFunction = nil,

function FileFoundCallbackFunction = nil )

Description

Searches for files on the local system.

Parameters

Folder

(string) The path to the folder that you want to search in.

Filename

(string) The name of the file that you want to search for. You can use the * and ? wildcards in this field to search for files that match a specific pattern.

Recurse

(boolean) Whether to recurse through subfolders during the search:

VALUE | DESCRIPTION
true | Recurse.
false | Don't recurse. (Default)

IncludeFolders

(boolean) Whether to include (in the result) all folder paths that were encountered during the file search.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the find operation. (You can use this callback function to display the progress of the find operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

CurrentPath

(string) The current path being searched.

The callback function should return a boolean value (true or false) indicating whether the find operation should continue:

VALUE | DESCRIPTION
true | Continue with the find operation.
false | Stop the find operation as soon as possible.

FileFoundCallbackFunction

(function) The name of a function that will be called whenever a file is found that matches the search criteria. You can use this function to exit the search operation based on the file that was found; for example, if you wanted to exit the search after the first file was found.

The callback function must be able to receive the following parameters:

FoundPath

(string) The path to the file that was found.

The callback function should return a boolean value (true or false) indicating whether the find operation should continue:

VALUE | DESCRIPTION
true | Continue with the find operation.
false | Stop the find operation as soon as possible.

Returns

(table) A table containing the paths to all of the files that were found. If no files were found or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: If IncludeFolders is true, the result will always include the folders that were encountered during the search.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.GetAttributes

table File.GetAttributes (

string Filename )

Description

Returns a table containing all of the attributes for a specific file.

Parameters

Filename

(string) The path to the file.

Returns

(table) A table containing the file attributes indexed by name. If the file does not exist or an error occurs, this action returns nil.

If the file exists, the following attributes will be stored in the table:

KEY | TYPE | DESCRIPTION
CreationDate | string | The date the file was created (Monday, May 26, 2003).
CreationDateISO | string | The date the file was created, in ISO format (2003-05-26T16:57:52).
AccessDate | string | The last date the file was accessed (Wednesday, June 18, 2003).
AccessDateISO | string | The last date the file was accessed, in ISO format (2003-06-18T15:11:44).
WriteDate | string | The last date the file was written to (Wednedsay, June 18, 2003).
WriteDateISO | string | The last date the file was written to, in ISO format (2003-06-18T14:55:05).
Directory | boolean | True if the directory attribute is set.
Archived | boolean | True if the archive file attribute is set.
ReadOnly | boolean | True if the read-only file attribute is set.
Compressed | boolean | True if the compressed file attribute is set.
System | boolean | True if the system file attribute is set.
Hidden | boolean | True if the hidden file attribute is set.
Temporary | boolean | True if the temporary file attribute is set.
Normal | boolean | True if none of the boolean attributes are set.

You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.GetCRC

number File.GetCRC (

string Filename )

Description

Returns the CRC value for a specific file.

Parameters

Filename

(string) The full path to the file.

Returns

(number) The numeric CRC value for the given file. If this action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.GetDefaultViewer

string File.GetDefaultViewer (

string FileExtension )

Description

Returns the path to the default viewer application associated with a specific file extension.

Parameters

FileExtension

(string) The file extension (e.g. ".jpg" or ".txt").

Note: You can include or omit the dot (.) in the file extension. For example, ".pdf" and "pdf" will both work fine.

Returns

(string) The path to the default viewer application. If this action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.GetShortName

string File.GetShortName (

string Filename )

Description

Gets the "8.3" version of the full path to an existing file.

Note: If the file does not exist, this action will fail and an empty string will be returned.

Parameters

Filename

(string) The full path to the file.

Returns

(string) The "8.3" version of the given file path. If this action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.GetSize

number File.GetSize (

string Filename )

Description

Returns the size of a file in bytes.

Parameters

Filename

(string) The full path to the file.

Returns

(number) The size of the given file in bytes. If this action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.GetVersionInfo

table File.GetVersionInfo (

string Filename )

Description

Returns a table containing the all of the version information for a specific file.

Note: Some files may not have any version information. Program executables and DLLs generally do, though.

Parameters

Filename

(string) The path to the file.

Returns

(table) A table containing the file version information indexed by name. If the version information could not be retrieved (for example, the file wasn't found), nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

If the file exists (and has version information in it), the following information will be stored in the table:

KEY | TYPE | DESCRIPTION
FileVersion | string | The file version, as it appears on the Version tab when you right-click on a file and choose Properties. ("5.0.0.1"). If this information cannot be determined, a blank string is returned.
ProductVersion | string | The version number for the product with which the file is distributed. ("1.0.0.6") If this information cannot be determined, a blank string is returned.
CompanyName | string | The company that produced the file. ("Super Dooper Inc.") If this information cannot be determined, a blank string is returned.
FileDescription | string | A short string describing the file. ("Doopernator program file for XP.") If this information cannot be determined, a blank string is returned.
InternalName | string | The internal name of the file, if one exists. ("Doopernator") If this information cannot be determined, a blank string is returned.
ProductName | string | The name of the product with which the file is distributed. ("Doopernator XP") If this information cannot be determined, a blank string is returned.
LegalCopyright | string | All copyright notices that apply to the file. ("Copyright (C) 2003 Super Dooper Inc.") If this information cannot be determined, a blank string is returned.
LegalTrademarks | string | All trademarks and registered trademarks that apply to the file. ("Doopernator is a registered trademark of Super Dooper Inc., so you better not try calling anything Doopernator or our lawyers will hunt you down like terriers chasing a baleful of mice.") If this information cannot be determined, a blank string is returned.
Comments | string | Additional information. ("For more information, visit www.doopernator.com.") If this information cannot be determined, a blank string is returned.
OriginalFilename | string | The original name of the file, not including a path. This lets an application determine whether a file has been renamed by the user. ("Doopernator.exe") If this information cannot be determined, a blank string is returned.
PrivateBuild | string | Information about the file if it's a private or "internal" version. ("Built by BIGDOG on SUPER22.") If this information cannot be determined, a blank string is returned.
SpecialBuild | string | How this version of the file differs from the standard version if it's a special build. ("Built to test the doopernator optimizer code on PCs running service pack 1 with DirectX 9.1.") If this information cannot be determined, a blank string is returned.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.Install

boolean File.Install (

string Filename,

string Destination,

number Overwrite = 0,

boolean CreateBackup = false,

boolean SharedSystem = false,

function ProgressCallbackFunction = nil,

function OverwriteCallbackFunction = nil )

Description

Installs a file onto the user's system.

Note: This is just like copying the file, but with a few more options.

Parameters

Filename

(string) The path to the file that you want to install.

Destination

(string) The full path and filename of the destination that you want to install to.

Overwrite

(number) Whether to overwrite a file in the destination folder if it has the same name as the file being installed:

CONSTANT | VALUE | DESCRIPTION
FILE_INSTALL_SAMEOLDER | 0 | Only overwrite the existing file if it's older than the file being installed, or if both files are the same age. (Default)
FILE_INSTALL_OLDER | 1 | Only overwrite the existing file if it's older than the file being installed.
FILE_INSTALL_ALWAYS | 2 | Always install the file, even if the existing file is newer.
FILE_INSTALL_NEVER | 3 | Never install the file, even if the existing file is older.
FILE_INSTALL_ASK | 4 | Ask the user if the existing file should be overwritten.
FILE_INSTALL_CALLBACK | 6 | Call the OverwriteCallbackFunction to handle the overwriting of the file in a custom way.

Warning: It is generally not a good idea to choose FILE_INSTALL_ALWAYS unless you are certain that this is what you want to do. Also, do not choose FILE_INSTALL_ASK unless you are confident that the user will have the knowledge to make such a decision. FILE_INSTALL_SAMEOLDER is generally the safest choice.

CreateBackup

(boolean) Whether to create a backup of the existing file (if there is one) during the installation:

VALUE | DESCRIPTION
true | Any existing file will be renamed to filename.bak. If filename.bak already exists, the file will be renamed to filename.bk1 instead, or filename.bk2, or filename.bk3, etc. The new file will only be installed after the existing one has been backed up.
false | Don't backup the existing file. (Default)

SharedSystem

(boolean) Whether the file is a system file that may be shared by multiple programs:

VALUE | DESCRIPTION
true | Keep a usage count for the file during installation and uninstallation to make sure it isn't removed when it's still needed.
false | The file isn't going to be shared, so don't keep a usage count. (Default)

ProgressCallbackFunction

(function) The name of a function that will be called whenever progress is made in the install operation. (You can use this callback function to display the progress of the install operation in your own custom way.)

Note: If ProgressCallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being installed.

Destination

(string) The destination path for file being installed.

Copied

(number) The number of bytes installed so far.

Total

(number) The total bytes that will be installed.

The callback function should return a boolean value (true or false) indicating whether the install operation should continue:

VALUE | DESCRIPTION
true | Continue with the install operation.
false | Stop the install operation as soon as possible.

OverwriteCallbackFunction

(function) The name of a function that will be called whenever an overwrite decision must be made. (You can use this callback function to handle the overwrite operation in your own custom way.)

Note: If OverwriteCallbackFunction is set to nil, then the FILE_INSTALL_SAMEOLDER overwrite option will be used.

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file to install.

Destination

(string) The destination path for file being installed.

The callback function should return a boolean value (true or false) indicating whether or not to overwrite the file:

VALUE | DESCRIPTION
true | Overwrite the file.
false | Do not overwrite the file.

Returns

(boolean) True if the file was installed, or false if it wasn't or if an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.

Note: If the destination file already exists and is protected by Windows File Protection (WFP), false will be returned.


File.IsInUse

boolean File.IsInUse (

string Filename )

Description

Returns true if a file is in use at a specific location or false if it is not. If a file is in use it cannot be copied over or deleted.

Parameters

Filename

(string) The path to the file.

Returns

(boolean) True if the file is in use, or false if it is not, or if an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


File.Move

File.Move (

string Source,

string Destination,

boolean Recurse = true,

boolean Overwrite = true,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Description

Moves a file to another location.

Parameters

Source

(string) The path to the file that you want to move. You can use the * and ? wildcards in this field to move multiple files.

Destination

(string) The path to the destination folder or file that you want to move to.

Warning: Any folders in the destination path must already exist when performing this action, or an error will result.

Tip: You can use a Folder.Create action to create a destination folder if necessary.

Recurse

(boolean) Whether to recurse through subfolders when a wildcard is used in the Source parameter:

VALUE | DESCRIPTION
true | Recurse. (Default)
false | Don't recurse.

Overwrite

(boolean) Whether to overwrite any files in the destination folder if they have the same names as the files being moved:

VALUE | DESCRIPTION
true | Move the source files right over the destination files. (Default)
false | Don't move a file if another file with the same name already exists in the destination folder.

AbortOnFail

(boolean) Whether to abort the move operation if an error occurs:

VALUE | DESCRIPTION
true | Stop moving as soon as the first error occurs.
false | Continue moving files even if some files fail to move. (Default)

IncludeHiddenFiles

(boolean) Whether to move files that have the "hidden" or "system" attributes set:

VALUE | DESCRIPTION
true | Move files even if they have the "hidden" or "system" attributes set.
false | Don't move any files that have the "hidden" or "system" attributes set. (Default)

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the move operation. (You can use this callback function to display the progress of the move operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being copied.

Destination

(string) The destination path for file being copied.

Copied

(number) The number of bytes copied so far.

Total

(number) The total bytes that will be copied.

FileCopied

(number) The number of bytes of the current file moved so far.

FileTotal

(number) The current file's total bytes that will be moved.

The callback function should return a boolean value (true or false) indicating whether the move application should continue:

VALUE | DESCRIPTION
true | Continue with the move operation.
false | Stop the move operation as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.MoveOnReboot

File.MoveOnReboot (

string Source,

string Destination )

Description

Moves a file from one location to another on the next system reboot.

Parameters

Source

(string) The full path to the file you want to move.

Destination

(string) The full destination path. This is the location you want the file moved to.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Open

File.Open (

string Filename,

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL )

Description

Opens a document file with its default viewer application.

Note: If this action fails with the "open" shell verb, it drops through and tries the default shell verb for the file type.

Parameters

Filename

(string) The path to the document. Click the browse button ( [image] ) to select a file.

WorkingFolder

(string) The working folder to set for the document.

Note: This sets the current directory for the operation to something other than the folder that the file is in. Normally, you can just leave it blank.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.OpenEmail

File.OpenEmail (

string EmailAddress,

number WindowMode = SW_SHOWNORMAL )

Description

Opens the user's default email client with an email address in the "To" field.

Note: If this action fails with the "open" shell verb, it will drop through and try using the default shell verb to open the email message.

Parameters

EmailAddress

(string) The email address that will appear in the "To" field.

Tip: You can automatically fill in the subject field, too. Just type "?subject=" (without quotes) after the email address, followed by the text that you want in the subject line. For example:

"joe@exampledomain.com?subject=Help"

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.OpenURL

File.OpenURL (

string URL,

number WindowMode = SW_SHOWNORMAL )

Description

Opens a local file or web-based URL in the user's default Web browser.

Note: This action uses the default shell verb for the URL.

Parameters

URL

(string) The URL for the web page, or the path to the local file. Click the browse button ( [image] ) if you would like to select a local file.

Note: The "http://" prefix is optional, but it's generally a good idea to include it so the page will be located faster.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Print

File.Print (

string Filename )

Description

Prints a document on the user's default printer. This is the same as selecting "print" from the right-click context menu of the file you wish to print.

Note: The associated viewer application for the file type must support the "print" verb in order for this to work.

Parameters

Filename

(string) The path to the document.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Rename

File.Rename (

string OldName,

string NewName )

Description

Renames a file on the user's system.

Parameters

OldName

(string) The full path to the file you want to rename.

NewName

(string) The full path including the new name for the file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.Run

number File.Run (

string Filename,

string Args = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false )

Description

Runs an executable.

Note: If you are distributing on Windows Vista or later and have used a different requested execution level other than "Require administrator," you should use the Shell.Execute action instead.

Parameters

Filename

(string) The path to the executable (.exe) file.

Args

(string) The command line arguments to pass to the executable.

WorkingFolder

(string) The working folder to set for the executable file.

Note: This sets the current directory for the operation to something other than the folder that the file is in. Normally, you can just leave it blank.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.
SW_HIDE | 0 | Hide.

WaitForReturn

(boolean) Whether the application will wait until the executable has exited before continuing:

VALUE | DESCRIPTION
true | Wait.
false | Don't wait. (Default)

Note: This parameter must be set to true if you want to receive a process return code.

Returns

(number) The process return code if the WaitForReturn parameter is set to true. If WaitForReturn is set to false 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: On Windows Vista or later, if this action fails due to requiring elevation, error code 1045 is returned.

Note: If the specified process has not terminated, the termination status returned is STILL_ACTIVE. If the process has terminated, the termination status returned may be one of the following:

The exit value specified in the ExitProcess or TerminateProcess function.
The return value from the main or WinMain function of the process.
The exception value for an unhandled exception that caused the process to terminate.


File.RunAs

number File.RunAs (

string Filename,

string Args = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false,

string UserName = "",

string Password = "",

string Domain = "",

number LogonFlag = LOGON_NO_OPTION,

table CreationOptions = nil,

table ExtendedErrorInfo = nil )

Description

Runs an executable as a different user.

Parameters

Filename

(string) The path to the executable (.exe) file.

Args

(string) The command line arguments to pass to the executable.

WorkingFolder

(string) The working folder to set for the executable file.

Note: This sets the current directory for the operation to something other than the folder that the file is in. Normally, you can just leave it blank.

WindowMode

(number) The window mode to use:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | Normal. (Default)
SW_MAXIMIZE | 3 | Maximized.
SW_MINIMIZE | 6 | Minimized.
SW_HIDE | 0 | Hide.

WaitForReturn

(boolean) Whether the application will wait until the executable has exited before continuing:

VALUE | DESCRIPTION
true | Wait.
false | Don't wait. (Default)

Note: This parameter must be set to true if you want to receive a process return code.

UserName

(string) The username that will be used to run the file. You must use the UPN format, (eg. user@DNS_domain_name) if you are logging onto a network domain and you don't specify a Domain parameter.

Password

(string) The password for the specified user name.

Domain

(string) The domain or server that contains an account database for the specified user. If you do not specify a domain, the UserName parameter must be in UPN format (eg. user@DNS_domain_name) if you are logging onto a network domain.

LogonFlag

(number) The logon flag to use. Choose from:

CONSTANT

VALUE

DESCRIPTION

LOGON_NO_OPTION

0

Do not logon with any profile. (Default)

LOGON_WITH_PROFILE

1

Log on, then load the user profile in the HKEY_USERS registry key. Loading the profile can be time-consuming, so it is best to use this value only if you must access the information in the HKEY_CURRENT_USER registry key.

LOGON_NETCREDENTIALS_ONLY

2

Log on, but use the specified credentials on the network only. This value can be used to create a process that uses a different set of credentials locally than it does remotely. This is useful in inter-domain scenarios where there is no trust relationship.

Note: The system does not validate the specified credentials. Therefore, the process can start, but it may not have access to network resources.

CreationOptions

(table) A table containing the creation options by name that control how the process is created. In the table, a value of true turns an option on, and a value of false turns the option off. If nil is passed, DefaultErrorMode, NewConsole and NewProcessGroup are set to true by default.

The following options can be set or unset in the table:

KEY | TYPE | DESCRIPTION
DefaultErrorMode | boolean | The new process does not inherit the error mode of the calling process. Instead, it gives the new process the current default error mode. You can pass false to inherit the error mode of the calling process, eg. {DefaultErrorMode=false}
NewConsole | boolean | Whether or not the new process has a new console, instead of inheriting the parent's console. eg. {NewConsole=false}
NewProcessGroup | boolean | Whether or not the new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. eg. {NewProcessGroup=false}
SeparateWOWVDM | boolean | Note: This flag is only valid starting a 16-bit Windows-based application. Whether or not the new process runs in a private Virtual DOS Machine (VDM). By default, all 16-bit Windows-based applications run in a single, shared VDM. The advantage of running separately is that a crash only terminates the single VDM; any other programs running in distinct VDMs continue to function normally. Also, 16-bit Windows-based applications that run in separate VDMs have separate input queues, which means that if one application stops responding momentarily, applications in separate VDMs continue to receive input. eg. {SeparateWOWVDM=true}
Suspended | boolean | Whether or not the primary thread of the new process is created in a suspended state. eg.{Suspended=true}
UnicodeEnvironment | boolean | Whether or not the environment block uses Unicode characters. Otherwise, the environment block uses ANSI characters. eg. {UnicodeEnvironment=true}

ExtendedErrorInfo

(table) A table that will be filled with extended error information indexed by the following keys:

KEY | TYPE | DESCRIPTION
ErrorCode | number | The Windows error code.
ErrorMsg | string | The Windows error message.

Note: Since this parameter requires a table, you must first create the table before the action is called, for example, TableName={};

Returns

(number) The process return code if the WaitForReturn parameter is set to true. If WaitForReturn is set to false 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: The termination status returned may be one of the following:

The exit value specified in the ExitProcess or TerminateProcess function.
The return value from the main or WinMain function of the process.
The exception value for an unhandled exception that caused the process to terminate.


File.RunOnReboot

File.RunOnReboot (

string Filename,

string Args = "" )

Description

Runs an executable the next time the system is rebooted.

Parameters

Filename

(string) The path to the executable (.exe) file.

Args

(string) The command line arguments to pass to the executable.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.SetAttributes

File.SetAttributes (

string Filename,

table Attributes )

Description

Sets the attributes of a file.

Parameters

Filename

(string) The path to the file.

Attributes

(table) A table containing the file attributes that you want to modify, indexed by name. In the table, a value of true turns an attribute on, and a value of false turns the attribute off.

The following attributes can be set or unset in the table:

KEY | TYPE | DESCRIPTION
Archived | boolean | Sets or unsets the archive file attribute.
ReadOnly | boolean | Sets or unsets the read-only file attribute.
Compressed | boolean | Sets or unsets the compressed file attribute.
System | boolean | Sets or unsets the system file attribute.
Hidden | boolean | Sets or unsets the hidden file attribute.
Temporary | boolean | Sets or unsets the temporary file attribute.
Normal | boolean | When used alone (when it is the only attribute in the table), setting Normal to true will unset all of the other attributes. Otherwise, it is simply ignored.

Note: If there are any other keys in the table, they will be ignored.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


File.SetPermissions

number File.SetPermissions (

string Filename,

string UserSID = SID_EVERYBODY,

number AccessMode = SET_ACCESS,

number Permissions = ALL_PERMISSIONS,

number Inheritance = SUB_CONTAINERS_AND_OBJECTS_INHERIT )

Description

Sets the permissions of a file or folder.

Parameters

Filename

(string) The full path to the file or folder whose permissions will be set.

UserSID

(string) The SID of the user or group whose permissions will be altered. You may use any valid string or choose from the following built-in SID constants:

Tip: You can also use the System.GetUserSID action to get the SID value from a username on the local computer.

CONSTANT | VALUE | DESCRIPTION
SID_NULL | "S-1-0" | A NULL authority.
SID_NOBODY | "S-1-0-0" | Nobody.
SID_EVERYBODY | "S-1-1-0" | Everyone, a group that contains all users except for anonymous users on all systems greater than or equal to Windows XP SP2.
SID_CREATOR_AUTHORITY | "S-1-3" | An identifier authority representing the creator authority.
SID_CREATOR_OWNER | "S-1-3-0" | The current owner of the file object.
SID_NETWORK | "S-1-5-2" | A group containing all users that have logged on using a network connection.
SID_AUTHENTICATED_USERS | "S-1-5-11" | A group containing all users that were authenticated when they logged on.
SID_ADMINISTRATORS | "S-1-5-32-544" | The built-in administrators group.
SID_USERS | "S-1-5-32-545" | The built-in users group.
SID_GUESTS | "S-1-5-32-546" | The built-in guests group.
SID_POWER_USERS | "S-1-5-32-547" | The built-in power users group.
SID_LAUNCH_USER_USER | "LaunchUser" | The user who launched the setup. This is the same user whose information is used to populate the launch user variables.

AccessMode

(number) Controls how the permissions will be applied. Choose from:

Note: This value can also be any of the available access modes available in the ACCESS_MODE enumeration: http://msdn.microsoft.com/en-us/library/aa374899(VS.85).aspx

CONSTANT | VALUE | DESCRIPTION
NOT_USED_ACCESS | 0 | Not used.
GRANT_ACCESS | 1 | Combines the new permissions with the existing permissions for the user or group.
SET_ACCESS | 2 | Set the permissions for the user or group overriding any existing information.
DENY_ACCESS | 3 | Deny the user the permissions specified, this will not override any existing denied rights.
REVOKE_ACCESS | 4 | Remove any existing privileges for the user or group.

Permissions

(number) The permissions that will be used by the actions. Choose from one of the following or specify your own valid value:

Note: Please see: http://msdn.microsoft.com/en-us/library/aa446627%28VS.85%29.aspx for more information.

CONSTANT | VALUE | DESCRIPTION
READ_PERMISSIONS | 1179785 | Read permissions.
WRITE_PERMISSIONS | 1179926 | Write permissions.
EXECUTE_PERMISSIONS | 538050697 | Read and Execute permissions.
ALL_PERMISSIONS | 268435456 | Full control permissions.
MODIFY_PERMISSIONS | 1245631 | Modify (includes Read, Write, and Execute) permissions.
READ_WRITE_PERMISSIONS | 1180063 | Read and Write permissions.
READ_WRITE_EXECUTE_PERMISSIONS | 538050975 | Read, Write, and Execute permissions.

Inheritance

(number) The inheritance rules for the permissions that will be applied. Choose from, or specify a valid value:

Note: Please see: http://msdn.microsoft.com/en-us/library/aa446627%28VS.85%29.aspx for more information.

CONSTANT | VALUE | DESCRIPTION
NO_INHERITANCE | 0 | The permissions are not inheritable.
SUB_OBJECTS_ONLY_INHERIT | 1 | Only non-container objects within the file object will inherit the permissions.
SUB_CONTAINERS_ONLY_INHERIT | 2 | Only container objects within the file object will inherit the permissions.
SUB_CONTAINERS_AND_OBJECTS_INHERIT | 3 | Both objects and containers that are contained by the file object will inherit the permissions.
INHERIT_NO_PROPAGATE | 4 | Meaning to be determined by Microsoft.
INHERIT_ONLY | 8 | Meaning to be determined by Microsoft.

Returns

(number) Returns 0 if successful. If this action fails, a non-zero error code will be returned defined in the Microsoft's WinError.h header file. For more information on the possible error codes please see: http://msdn.microsoft.com/en-us/library/ms819772.aspx.


Folder.Create

Folder.Create (

string Folder )

Description

Creates a new folder on the user's system.

Parameters

Folder

(string) The path to the folder.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.Delete

Folder.Delete (

string Folder )

Description

Deletes a folder from the user's system.

Note: The folder must be empty to be deleted.

Parameters

Folder

(string) The path to the folder.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.DeleteTree

Folder.DeleteTree (

string FolderName,

function CallbackFunction = nil )

Description

Deletes a folder and all of its contents (files and subfolders) from the user's system.

Parameters

FolderName

(string) The path to the folder.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the delete operation. (You can use this callback function to display the progress of the delete operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

Source

(string) The source path of the file being deleted.

Deleted

(number) The number of files deleted so far.

Total

(number) The total number of files that will be deleted.

The callback function should return a boolean value (true or false) indicating whether the delete operation should continue:

VALUE | DESCRIPTION
true | Continue with the delete operation.
false | Stop the delete operation as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.DoesExist

boolean Folder.DoesExist (

string Folder )

Description

Returns true if a specific folder exists and false if it doesn't.

Parameters

Folder

(string) The path to the folder.

Returns

(boolean) True if the folder exists, false if it doesn't or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Folder.Find

table Folder.Find (

string StartFolder,

string Folder,

boolean Recurse = false,

function CallbackFunction = nil )

Description

Searches for folders on the local system.

Parameters

StartFolder

(string) The path to the folder that you want to search in.

Folder

(string) The name of the folder that you want to search for. You can use the * and ? wildcards in this field to search for folders that match a specific pattern.

Recurse

(boolean) Whether to recurse through subfolders during the search:

VALUE | DESCRIPTION
true | Recurse.
false | Don't recurse. (Default)

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the find operation. (You can use this callback function to display the progress of the find operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

CurrentPath

(string) The current path being searched.

The callback function should return a boolean value (true or false) indicating whether the find operation should continue:

VALUE | DESCRIPTION
true | Continue with the find operation.
false | Stop the find operation as soon as possible.

Returns

(table) A table containing the paths to all of the folders that were found. If no folders were found or the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Folder.GetCurrent

string Folder.GetCurrent (

)

Description

Returns the "current folder" (working directory) for the installation.

Parameters

None.

Returns

(string) The path to the "current folder" (working directory) for the installation. If the current folder cannot be determined, a blank string "" is returned.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Folder.Rename

Folder.Rename (

string OldName,

string NewName )

Description

Renames a folder on the user's system.

Parameters

OldName

(string) The path to the folder you want to rename.

NewName

(string) The new path to the folder. This must include the full path and folder name.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Folder.SetCurrent

Folder.SetCurrent (

string Folder )

Description

Sets the installation's "current folder" (working directory).

Parameters

Folder

(string) The path to the folder.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.Download

HTTP.Download (

string URL,

string Filename,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Description

Downloads a file from an Internet Web site.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for the download by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to download.

Filename

(string) The destination path and filename of the file you want to download. For example, C:\\MyFolder\\patch.zip.

Mode

(number) The mode you want to use to save the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
MODE_BINARY | 0 | Save the file exactly as downloaded. (Default)
MODE_TEXT | 1 | Convert the file from Unix to Windows text mode, if necessary.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Note: Timeout values are interpreted in multiple ways during client server communication. As a result the actual timeout used by the connection may differ from the value specified.

Port

(number) The port to connect to. In most cases the default value of 80 is fine.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the download does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the download operation. (You can use this callback function to display the progress of the download in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

BytesRead

(number) The number of bytes that have been downloaded so far.

FileSize

(number) The file size in bytes or 0 if the file size could not be retrieved from the server.

TransferRate

(number) The current transfer rate in Kilobytes per second.

SecondsLeft

(number) The estimated number of seconds left in the download.

SecondsLeftFormat

(string) The estimated number of seconds left formatted as a string in the form of: ""MM:SS".

Message

(string) Either a blank string ("") or an information message being sent by the server, such as "Resolving host name" or "Connecting to Server."

Note: If this parameter is not a blank string, it means that it is in a busy state, either before the download has begun, or at the end of the download. In this case all other parameters will be ignored.

The callback function should return a boolean value (true or false) indicating whether the download should continue:

VALUE | DESCRIPTION
true | Continue with the file download.
false | Stop the file download as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.DownloadSecure

HTTP.DownloadSecure (

string URL,

string Filename,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Description

Downloads a file from an Internet Web site using HTTPS (secure hypertext transfer protocol).

The secure hypertext transfer protocol (HTTPS) is a communications protocol designed to transfer encrypted information between computers over the World Wide Web. HTTPS is http using a Secure Socket Layer (SSL). A secure socket layer is an encryption protocol invoked on a Web server that uses HTTPS.

Note: The successful use of the HTTPS protocol requires a secure server to handle the request.

Note: This action requires that the end user has Internet Explorer version 4.0 or greater installed.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for the download by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to download.

Filename

(string) The destination path and filename of the file you want to download. For example, C:\\MyFolder\\patch.zip.

Mode

(number) The mode you want to use to save the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
MODE_BINARY | 0 | Save the file exactly as downloaded. (Default)
MODE_TEXT | 1 | Convert the file from Unix to Windows text mode, if necessary.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Note: Timeout values are interpreted in multiple ways during client server communication. As a result the actual timeout used by the connection may differ from the value specified.

Port

(number) The port to connect to. The default value is 443.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the download does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the download operation. (You can use this callback function to display the progress of the download in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

BytesRead

(number) The number of bytes that have been downloaded so far.

FileSize

(number) The file size in bytes, 0 if the file size could not be retrieved from the server.

Note: If a redirection is used when accessing the file, it's size may not be available and zero will be passed as FileSize.

TransferRate

(number) The current transfer rate in Kilobytes per second.

SecondsLeft

(number) The estimated number of seconds left in the download.

SecondsLeftFormat

(string) The estimated number of seconds left formatted as a string in the form of: ""MM:SS".

Message

(string) Either a blank string ("") or an information message being sent by the server, such as "Resolving host name" or "Connecting to Server."

Note: If this parameter is not a blank string, it means that it is in a busy state, either before the download has begun, or at the end of the download. In this case all other parameters will be ignored.

The callback function should return a boolean value (true or false) indicating whether the download should continue:

VALUE | DESCRIPTION
true | Continue with the file download.
false | Stop the file download as soon as possible.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.GetConnectionState

table HTTP.GetConnectionState (

)

Description

Retrieves the connected state of the local system.

Note: This action requires that the end user has Internet Explorer version 4.0 or greater installed.

Note: You cannot rely solely on the fact that the Connected result of HTTP.GetConnectionState returning true means that you have a valid active Internet connection. It is impossible for HTTP.GetConnectionState to determine if the entire connection to the Internet is functioning without sending a request to a server. This is why you need to send a request to determine if you are really connected or not. You can be assured however that if the Connected value of HTTP.GetConnectionState returns true, that attempting your connection will NOT cause you to be prompted to connect to the default Internet Service Provider.

Parameters

None.

Returns

(table) A table containing the user's Internet connection information, indexed by the following categories:

Note: If the user has a version of Internet Explorer that is less than 4.0, nil will be returned.

KEY | TYPE | DESCRIPTION
Connected | boolean | Whether or not the user is connected to the Internet. If the user is connected, true is returned. If they are not connected, false is returned. You can access this value using tb.Connected.
Modem | boolean | Whether or not the local system uses a modem to connect to the Internet. If a modem is used, true is returned. If a modem is not used, false is returned. You can access this value using tb.Modem.
LAN | boolean | Whether or not the local system uses a local area network to connect to the Internet. If a LAN is used, true is returned. If a LAN is not used, false is returned. You can access this value using tb.Lan.
Proxy | boolean | Whether or not the local system uses a proxy server to connect to the Internet. If a proxy server is used, true is returned. If a proxy server is not used, false is returned. You can access this value using tb.Proxy.
RASInstalled | boolean | Whether or not the local system has RAS (Remote Access Service) installed. If a RAS is installed, true is returned. If RAS is not installed, false is returned. You can access this value using tb.RASInstalled.
ConnectionOffline | boolean | Whether or not the local system is in offline mode. If the system is offline, true is returned. If the system is not offline, false is returned. You can access this value using tb.ConnectionOffline.
ConnectionConfigured | boolean | Whether or not the local system has a valid connection to the Internet, but it might or might not be currently connected. If the system has a valid connection, true is returned. If the system does not have a valid connection, false is returned. You can access this value using tb.ConnectionConfigured.

You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


HTTP.GetFileSize

number HTTP.GetFileSize (

string URL,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Description

Gets the size (in bytes) of a file located on an Internet Web site.

Note: The default proxy settings that are currently configured through Internet Explorer will be used to get the file size by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to get the size of.

Mode

(number) The mode you want to use to access the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
MODE_BINARY | 0 | Save the file exactly as downloaded. (Default)
MODE_TEXT | 1 | Convert the file from Unix to Windows text mode, if necessary.

Note: This parameter is mainly present for consistency between HTTP actions.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Note: Timeout values are interpreted in multiple ways during client server communication. As a result the actual timeout used by the connection may differ from the value specified.

Port

(number) The port to connect to. In most cases the default value of 80 is fine.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If accessing the file does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the file access operation. (You can use this callback function to display the progress of the operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameter:

Message

(string) Either a blank string ("") or an information message being sent by the server, such as "Resolving host name" or "Connecting to Server."

The callback function should return a boolean value (true or false) indicating whether the file access should continue:

VALUE | DESCRIPTION
true | Continue with the file access.
false | Stop the file access as soon as possible.

Returns

(number) The size of the file on the Internet Web site (in bytes). If the file's size could not be retrieved, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.GetFileSizeSecure

number HTTP.GetFileSizeSecure (

string URL,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Description

Gets the size of a file (in bytes) located on an Internet Web site using HTTPS (secure hypertext transfer protocol).

The secure hypertext transfer protocol (HTTPS) is a communications protocol designed to transfer encrypted information between computers over the World Wide Web. HTTPS is http using a Secure Socket Layer (SSL). A secure socket layer is an encryption protocol invoked on a Web server that uses HTTPS.

Note: The successful use of the HTTPS protocol requires a secure server to handle the request.

Note: This action requires that the end user has Internet Explorer version 4.0 or greater installed.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for the download by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to get the size of.

Mode

(number) The mode you want to use to access the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
MODE_BINARY | 0 | Save the file exactly as downloaded. (Default)
MODE_TEXT | 1 | Convert the file from Unix to Windows text mode, if necessary.

Note: This parameter is mainly present for consistency between HTTP actions.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Note: Timeout values are interpreted in multiple ways during client server communication. As a result the actual timeout used by the connection may differ from the value specified.

Port

(number) The port to connect to. The default value is 443.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the download does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the file access operation. (You can use this callback function to display the file access operation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameter:

Message

(string) Either a blank string ("") or an information message being sent by the server, such as "Resolving host name" or "Connecting to Server."

The callback function should return a boolean value (true or false) indicating whether the file access should continue:

VALUE | DESCRIPTION
true | Continue with the file access.
false | Stop the file access as soon as possible.

Returns

(number) The size of the file on the Internet Web site (in bytes). If the file's size could not be retrieved, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.GetHTTPErrorInfo

table HTTP.GetHTTPErrorInfo (

)

Description

Retrieves HTTP specific information about the last HTTP action that was performed.

For example, if you perform an HTTP.Download and an error occurs, you can use this action to retrieve HTTP information about that error.

Parameters

None.

Returns

(table) A table containing the HTTP error information indexed by the following keys:

KEY | TYPE | DESCRIPTION
Number | number | The WinInet error code.
Message | string | The WinInet Error string associated with the error code.
Status | number | The HTTP status code associated with the last error. Status codes are categorized into the following groups: 200-299 Success 300-399 Information 400-499 Request error 500-599 Server error Some common HTTP Status Codes: 200 URL located, transmission follows 400 Unintelligible request 404 Requested URL not found 405 Server does not support requested method 500 Unknown server error 503 Server capacity reached

Note: The Number and Message fields in the table generally report on whether the HTTP transaction itself was successful, for example the proper parameters were passed, an internet connection existed, and the information was actually sent to the server. The Status field contains information on the overall status of the operation at the server end, such as whether the server understood the request, and whether it was actually able to serve up the requested file.

You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


HTTP.Submit

string HTTP.Submit (

string URL,

table Values,

number Method = SUBMITWEB_GET,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil )

Description

Submits data to an Internet Web site and returns the response from the server.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for submitting the data by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to submit to.

Values

(table) The table of named value pairs to pass to the script. Each named value pair should have the form name="value".

For Example: {color="silver", make="Porsche", model="911 Turbo"}

Method

(number) The submission method to use. Choose from:

CONSTANT | VALUE | DESCRIPTION
SUBMITWEB_GET | 1 | The GET method will be used to submit the data. (Default)
SUBMITWEB_POST | 0 | The POST method will be used to submit the data.

Note: If you are not sure of the difference, please consult a book or Web site about CGI programming.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Note: Timeout values are interpreted in multiple ways during client server communication. As a result the actual timeout used by the connection may differ from the value specified.

Port

(number) The port to connect to. In most cases the default value of 80 is fine.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the submission does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

Returns

(string) The contents of the file returned by the web script. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.SubmitSecure

string HTTP.SubmitSecure (

string URL,

table Values,

number Method = SUBMITWEB_GET,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil )

Description

Submits data to an Internet Web site using HTTPS (secure hypertext transfer protocol) and returns the response from the server.

The secure hypertext transfer protocol (HTTPS) is a communications protocol designed to transfer encrypted information between computers over the World Wide Web. HTTPS is http using a Secure Socket Layer (SSL). A secure socket layer is an encryption protocol invoked on a Web server that uses HTTPS.

Note: The successful use of the HTTPS protocol requires a secure server to handle the request.

Note: This action requires that the end user has Internet Explorer version 4.0 or greater installed.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for submitting the data by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to the file you want to submit to.

Values

(table) The table of named value pairs to pass to the script. Each named value pair should have the form name="value".

For Example: {color="silver", make="Porsche", model="911 Turbo"}

Method

(number) The submission method to use. Choose from:

CONSTANT | VALUE | DESCRIPTION
SUBMITWEB_GET | 1 | The GET method will be used to submit the data. (Default)
SUBMITWEB_POST | 0 | The POST method will be used to submit the data.

Note: If you are not sure of the difference, please consult a book or Web site about CGI programming.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Note: Timeout values are interpreted in multiple ways during client server communication. As a result the actual timeout used by the connection may differ from the value specified.

Port

(number) The port to connect to. The port to connect to. The default value is 443.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the file. (This parameter is optional. If the submission does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

Returns

(string) The contents of the file returned by the web script. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


HTTP.TestConnection

boolean HTTP.TestConnection (

string URL,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil )

Description

Checks whether the user is connected to the Internet.

Note: The default proxy settings that are currently configured through Internet Explorer will be used for testing the connection by default, and is the recommended method. However if you require alternate proxy settings, they can be passed through the ProxyData parameter.

Tip: If this action fails, you can retrieve specific HTTP error details using HTTP.GetHTTPErrorInfo.

Parameters

URL

(string) The full URL to use to check the Internet connection. The action will attempt to connect to this URL in order to determine if a connection is available.

Note: If the URL involves redirection, the initial connection will indicate success, and the redirected URL will not be connected to.

Timeout

(number) The maximum time in seconds that the action will wait for a response after attempting to connect. The default value is 20.

Note: Timeout values are interpreted in multiple ways during client server communication. As a result the actual timeout used by the connection may differ from the value specified.

Port

(number) The port to connect to. In most cases the default value of 80 is fine.

AuthData

(table) A table containing basic HTTP authentication information that can be used to gain access to the site. (This parameter is optional. If the site does not require HTTP authentication, just leave this parameter blank.) The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
UserName | string | The user name to be used during HTTP authentication.
Password | string | The password to be used during HTTP authentication.

ProxyData

(table) A table containing the user's proxy information. You can pass nil (the default) to use the default proxy settings that are currently configured through Internet Explorer (recommended), or pass a table of specific proxy settings. (You may need to gather this information from the user.)

The table is indexed by the following keys:

KEY | TYPE | DESCRIPTION
PUserName | string | The proxy user name.
PPassword | string | The proxy password.
PServerAddress | string | The proxy server address.

Returns

(boolean) True if the URL could be connected to, or false if it could not or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


INIFile.DeleteSection

INIFile.DeleteSection (

string Filename,

string Section )

Description

Deletes a "section" in a specified INI file.

Parameters

Filename

(string) The path to the INI file.

Section

(string) The INI file section to delete.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


INIFile.DeleteValue

INIFile.DeleteValue (

string Filename,

string Section,

string Value )

Description

Deletes a "value" in a specified INI file.

Parameters

Filename

(string) The full path to the INI file.

Section

(string) The "section" containing the value.

Value

(string) The "value" to delete.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


INIFile.GetSectionNames

table INIFile.GetSectionNames (

string Filename )

Description

Returns all of the "section" names within an INI file.

Parameters

Filename

(string) The full path to the INI file.

Returns

(table) A table containing all of the "section" names within the specified INI file. If there are no section names or an error occurs (for example, the file doesn't exist), nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


INIFile.GetValue

string INIFile.GetValue (

string Filename,

string Section,

string Value )

Description

Returns the data associated with a "value" in a specified INI file.

Parameters

Filename

(string) The full path to the INI file.

Section

(string) The section containing the "value."

Value

(string) The "value" whose data you want.

Returns

(string) The data associated with the given "value" in the INI file. If the value doesn't exist or the action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


INIFile.GetValueNames

table INIFile.GetValueNames (

string Filename,

string Section )

Description

Returns all of the "value" names within in a section of an INI file.

Parameters

Filename

(string) The full path to the INI file.

Section

(string) The section whose value names you want.

Returns

(table) A table containing all of the "value" names within the given section. If there are no value names or an error occurs (for example, the file doesn't exist), nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


INIFile.SetValue

INIFile.SetValue (

string Filename,

string Section,

string Value,

string Data )

Description

Sets the data for an INI file value.

Parameters

Filename

(string) The full path to the INI file. If the file does not exist, it will be created.

Section

(string) The section containing the "value."

Value

(string) The "value" whose data you want to set.

Data

(string) The value data to set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Math.Abs

number Math.Abs (

number Num )

Description

Returns the absolute, positive value of a given number.

Parameters

Num

(number) The number whose absolute value you want.

Returns

(number) The absolute value of the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Acos

number Math.Acos (

number Num )

Description

Returns the arccosine (inverse cosine) of a number (in radians).

Parameters

Num

(number) The number whose arccosine value you want.

Note: This must be a number between -1 and 1.

Returns

(number) The arccosine of the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Asin

number Math.Asin (

number Num )

Description

Returns the arcsine (inverse sine) of a number (in radians).

Parameters

Num

(number) The number whose arcsine value you want.

Note: This must be a number between -1 and 1.

Returns

(number) The arcsine of the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Atan

number Math.Atan (

number Num )

Description

Returns the arctangent (inverse tangent) of a number (in radians).

Parameters

Num

(number) The number whose arctangent value you want.

Returns

(number) The arctangent of the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Atan2

number Math.Atan2 (

number Num1,

number Num2 )

Description

Returns the arctangent (inverse tangent) of Num1/Num2 (in radians).

Parameters

Num1

(number) The number to use as the dividend.

Num2

(number) The number to use as the divisor.

Returns

(number) The arctangent of Num1/Num2.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Ceil

number Math.Ceil (

number Num )

Description

Returns the nearest integer above a given value.

Note: This is the same as rounding up.

Parameters

Num

(number) The number whose ceiling you want.

Returns

(number) The nearest integer above the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Cos

number Math.Cos (

number Num )

Description

Returns the cosine (cos) of a number.

Parameters

Num

(number) The number whose cosine value you want (angle in radians).

Returns

(number) The cosine value of the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Deg

number Math.Deg (

number Radian )

Description

Converts a number from radians to degrees.

Parameters

Radian

(number) The number in radians.

Returns

(number) The equivalent number in degrees.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Exp

number Math.Exp (

number Num )

Description

Returns the exponential value of a number.

Parameters

Num

(number) The number whose exponential value you want.

Returns

(number) The exponential of the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Floor

number Math.Floor (

number Num )

Description

Returns the nearest integer below a given value.

Note: This is the same as rounding down.

Parameters

Num

(number) The number whose floor you want.

Returns

(number) The nearest integer below the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Frexp

table Math.Frexp (

number Num )

Description

Returns a table containing the mantissa (m) and exponent (n) of a number (x) in the equation x = m * 2^n.

Parameters

Num

(number) The number whose mantissa and exponent you want.

Returns

(table) A table containing the mantissa and exponent, indexed by "Mantissa" and "Exponent." The absolute value of the mantissa will be greater than or equal to 0.5 and less than 1.0.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.HexToNumber

number Math.HexToNumber (

string HexValue )

Description

Returns the equivalent decimal value of a hex value.

Parameters

HexValue

(string) The hex value you want to convert, for example "FFFF00".

Returns

(number) The converted hex value, in decimal format.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


Math.Ldexp

number Math.Ldexp (

number Mantissa,

number Exponent )

Description

Returns a number (x), given a mantissa (m) and an exponent (n) in the equation x = m * 2^n.

Parameters

Mantissa

(number) The mantissa value.

Exponent

(number) The exponent value.

Returns

(number) The number x in the equation x = m * 2^n.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Log

number Math.Log (

number Num )

Description

Returns the logarithm of a number.

Parameters

Num

(number) The number whose logarithm you want.

Returns

(number) The logarithm of the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Log10

number Math.Log10 (

number Num )

Description

Returns the base-10 logarithm of a number.

Parameters

Num

(number) The number whose base-10 logarithm you want.

Returns

(number) The base-10 logarithm of the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Max

number Math.Max (

number Num1,

number Num2 )

Description

Compares two numbers and returns the largest.

Parameters

Num1

(number) The first input number.

Num2

(number) The second input number.

Returns

(number) The larger of the two numbers.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Min

number Math.Min (

number Num1,

number Num2 )

Description

Compares two numbers and returns the smallest.

Parameters

Num1

(number) The first input number.

Num2

(number) The second input number.

Returns

(number) The smaller of the two numbers.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Mod

number Math.Mod (

number Num1,

number Num2 )

Description

Returns the modulus (remainder) of Num1/Num2.

Parameters

Num1

(number) The dividend.

Num2

(number) The divisor.

Returns

(number) The modulus of Num1/Num2.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Pow

number Math.Pow (

number Base = 2,

number Exponent = 4 )

Description

Returns the result of the calculation of Base raised to the power of Exponent.

Parameters

Base

(number) The base you want to have in the calculation.

Exponent

(number) The exponent you want to have in the calculation.

Returns

(number) The result of the calculation of Base raised to the power of Exponent.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Rad

number Math.Rad (

number Degree )

Description

Converts a number from degrees to radians.

Parameters

Degree

(number) The number in degrees.

Returns

(number) The equivalent number in radians.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Random

number Math.Random (

number Rand1 = nil,

number Rand2 = nil )

Description

Generates a random number.

Parameters

There are three ways you can use this action: with no parameters, with one parameter, or with two parameters.

If you don't provide any parameters, it will generate a random value between 0 and 1 (inclusive).

If you only provide the first parameter (Rand1), it will generate a random number between 1 and that number (inclusive).

If you provide both parameters (Rand1 and Rand2), it will generate a random number between those two numbers (inclusive).

Rand1

(number) The first number.

Rand2

(number) The second number.

Returns

(number) The random number that was generated.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.RandomSeed

Math.RandomSeed (

number Seed )

Description

Seeds the random number generator used by Math.Random.

If you use the same seed, you will produce the same sequence of pseudo-random numbers. In order to ensure a unique sequence of random numbers, use a unique seed value such as the current time and date.

Note: The random number generator is automatically seeded with a unique value using the current date and time when the application is started.

Parameters

Seed

(number) The seed value. This needs to be a value less than 2147483647.

Returns

Nothing.


Math.Round

number Math.Round (

number Num,

number DecimalPlaces = 0 )

Description

Returns the "rounded" version of a given number to the specified number of decimal places.

For example, given the number 4.6 and 0 decimal places, 5 is returned. Given the number 5.748 and 2 decimal places, 5.75 is returned.

Parameters

Num

(number) The number you want to round.

DecimalPlaces

(number) The number of decimal places you want to round the number to. If 0 is passed, the number will be rounded to the nearest integer. If 2 is passed, the number will be rounded to 2 decimal places.

Returns

(number) The "rounded" version of the given number. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Sin

number Math.Sin (

number Num )

Description

Returns the sine of a radian value.

Parameters

Num

(number) The angle in radians.

Returns

(number) The sine of the radian value.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Sqrt

number Math.Sqrt (

number Num )

Description

Returns the square root of a number.

Parameters

Num

(number) The positive number whose square root you want.

Returns

(number) The square root of the number.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Math.Tan

number Math.Tan (

number Num )

Description

Returns the tangent of a radian value.

Parameters

Num

(number) The angle in radians.

Returns

(number) The tangent of the radian value.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


MSI.ApplyPatch

boolean MSI.ApplyPatch (

string PatchPath,

string InstallPackage,

number InstallType,

string CommandLine = "" )

Description

Calls the MsiApplyPatch function to invoke an installation and set the PATCH property to the path of the patch package for each product listed by the patch package as eligible to receive it.

Note: You must set the REINSTALL property on the command line when applying a small update or minor upgrade patch. Without this property, the patch is registered on the system but cannot update files. For patches that do not use a Custom Action Type 51 to automatically set the REINSTALL and REINSTALLMODE properties, the REINSTALL property must be explicitly set with the CommandLine parameter. Set the REINSTALL property to list the features affected by the patch, or use a practical default setting of "REINSTALL=ALL". The default value of the REINSTALLMODE property is "omus". Beginning with Windows Installer version 3.0, the REINSTALL property is configured by the installer and does not need to be set on the command line.

Parameters

PatchPath

(string) The full path to the patch package.

InstallPackage

(string) If InstallType is set to INSTALLTYPE_NETWORK_IMAGE, this parameter should be the full path to the product that is to be patched. To make the installer apply the patch to every eligible product listed in the patch package, set this parameter to an empty string ("") and InstallType to INSTALLTYPE_DEFAULT.

If InstallType is set to INSTALLTYPE_SINGLE_INSTANCE, the installer applies the patch to the product specified by this parameter. In this case, other eligible products listed in the patch package are ignored and the this parameter should contain the a string representing the product code of the instance to patch. This type of installation requires the installer running Windows Server 2003 or Windows XP.

InstallType

(number) The type of installation to patch. Choose from:

CONSTANT | VALUE | DESCRIPTION
INSTALLTYPE_DEFAULT | 0 | Searches the system for products to patch. In this case, InstallPackage must be an empty string ("").
INSTALLTYPE_NETWORK_IMAGE | 1 | Specifies an administrative installation. In this case, InstallPackage must be set to a package path.
INSTALLTYPE_SINGLE_INSTANCE | 2 | Patch the product specified by InstallPackage. InstallPackage is the product code of the instance to patch. This type of installation requires the installer be running Windows Server 2003 family or Windows XP SP1. For more information see the MSDN topic, Installing Multiple Instances of Products and Patches.

CommandLine

(string) The command line property settings to use.

Returns

(boolean) Returns true if the action was successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.CloseHandle

boolean MSI.CloseHandle (

number MSIHandle )

Description

Calls the MsiCloseHandle function to close an open installation handle.

The following actions supply handles that should be closed after use by calling MSI.CloseHandle:

MSI.OpenPackage
MSI.OpenProduct

Parameters

MSIHandle

(number) The handle to an open installation.

Returns

(boolean) Returns true if the handle was closed successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.ConfigureFeature

boolean MSI.ConfigureFeature (

string ProductCode,

string FeatureID,

number InstallState )

Description

Calls the MsiConfigureFeature function to configure the installed state for a product feature.

Parameters

ProductCode

(string) The "product code" of the product to be configured. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

FeatureID

(string) The identifier of the feature to be configured.

InstallState

(number) The installation state for the feature. Choose from one of the following:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_ADVERTISED | 1 | The feature is advertised.
INSTALLSTATE_ABSENT | 2 | The feature is uninstalled.
INSTALLSTATE_LOCAL | 3 | The feature is installed locally.
INSTALLSTATE_SOURCE | 4 | The feature is installed to run from source.
INSTALLSTATE_DEFAULT | 5 | The feature is installed to its default location.

Returns

(boolean) Returns true if the action was successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.ConfigureProduct

boolean MSI.ConfigureProduct (

string ProductCode,

number InstallLevel,

number InstallState )

Description

Calls the MsiConfigureProduct function to install or uninstall a product.

Parameters

ProductCode

(string) The "product code" of the product you want to configure. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

InstallLevel

(number) How much of the product you want to install. Choose one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLLEVEL_DEFAULT | 0 | The authored default features are installed.
INSTALLLEVEL_MINIMUM | 1 | Only the required features are installed. You can specify a value between INSTALLLEVEL_MINIMUM and INSTALLLEVEL_MAXIMUM to install a subset of available features.
INSTALLLEVEL_MAXIMUM | 65535 | All features are installed. You can specify a value between INSTALLLEVEL_MINIMUM and INSTALLLEVEL_MAXIMUM to install a subset of available features.

InstallState

(number) The installation state for the product. Choose one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_ADVERTISED | 1 | The product is advertised.
INSTALLSTATE_ABSENT | 2 | The product is uninstalled.
INSTALLSTATE_LOCAL | 3 | The product is to be installed with all features installed locally.
INSTALLSTATE_SOURCE | 4 | The product is to be installed with all features installed to run from source.
INSTALLSTATE_DEFAULT | 5 | The product is to be installed with all features installed to the default states specified in the Feature Table.

Returns

(boolean) Returns true if the action was successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.ConfigureProductEx

boolean MSI.ConfigureProductEx (

string ProductCode,

number InstallLevel,

number InstallState,

string CommandLine = "" )

Description

Calls the MsiConfigureProductEx function to install or uninstall a product. A product command line can also be specified.

Parameters

ProductCode

(string) The "product code" of the product you want to configure. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

InstallLevel

(number) How much of the product you want to install. Choose one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLLEVEL_DEFAULT | 0 | The authored default features are installed.
INSTALLLEVEL_MINIMUM | 1 | Only the required features are installed. You can specify a value between INSTALLLEVEL_MINIMUM and INSTALLLEVEL_MAXIMUM to install a subset of available features.
INSTALLLEVEL_MAXIMUM | 65535 | All features are installed. You can specify a value between INSTALLLEVEL_MINIMUM and INSTALLLEVEL_MAXIMUM to install a subset of available features.

InstallState

(number) The installation state for the product. Choose one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_ADVERTISED | 1 | The product is advertised.
INSTALLSTATE_ABSENT | 2 | The product is uninstalled.
INSTALLSTATE_LOCAL | 3 | The product is to be installed with all features installed locally.
INSTALLSTATE_SOURCE | 4 | The product is to be installed with all features installed to run from source.
INSTALLSTATE_DEFAULT | 5 | The product is to be installed with all features installed to the default states specified in the Feature Table.

CommandLine

(string) The command-line property settings to use. This should be a list of the format "Property=Setting Property=Setting".

Returns

(boolean) Returns true if the action was successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnableLog

boolean MSI.EnableLog (

number LogMode,

string LogFile,

boolean Append = false,

boolean FlushEachLine = false )

Description

Calls the MsiEnableLog function to set the log mode for all subsequent installations that are initiated in the calling process. This action is usually called before calling the MSI.InstallProduct action.

Parameters

LogMode

(number) The log mode. Use the plus sign ("+") to combine values. If this value is zero and LogFile is nil, then logging will be turned off. Choose from one or more of the following:

CONSTANT | VALUE | DESCRIPTION
INSTALLLOGMODE_FATALEXIT | 1 | Logs out of memory or fatal exit information.
INSTALLLOGMODE_ERROR | 2 | Logs the error messages.
INSTALLLOGMODE_WARNING | 4 | Logs the warning messages.
INSTALLLOGMODE_USER | 8 | Logs the user requests.
INSTALLLOGMODE_INFO | 16 | Logs the status messages that are not displayed.
INSTALLLOGMODE_RESOLVESOURCE | 64 | Request to determine a valid source location.
INSTALLLOGMODE_OUTOFDISKSPACE | 128 | Indicates insufficient disk space.
INSTALLLOGMODE_ACTIONSTART | 256 | Logs the start of new installation actions.
INSTALLLOGMODE_ACTIONDATA | 512 | Logs the data record with the installation action.
INSTALLLOGMODE_PROPERTYDUMP | 1024 | Logs the property values at termination.
INSTALLLOGMODE_COMMONDATA | 2048 | Logs the parameters for user-interface initialization.
INSTALLLOGMODE_VERBOSE | 4096 | Sends large amounts of information to a log file not generally useful to users. May be used for technical support.
INSTALLLOGMODE_EXTRADEBUG | 8192 | Sends extra debugging information, such as handle creation information, to the log file. This feature is not supported on Windows XP.
INSTALLLOGMODE_LOGONLYONERROR | 16384 | Logging information is collected but is less frequently saved to the log file. This can improve the performance of some installations, but may have little benefit for large installations. The log file is removed when the installation succeeds. If the installation fails, all logging information is saved to the log file.

LogFile

(string) The full path and filename of the log file. Specify nil to turn logging off.

Append

(boolean) Whether the installer should append or overwrite any existing log file. Choose from:

VALUE | DESCRIPTION
true | Append to any existign log file specified in LogFile.
false | Overwrite any existing log file specified in LogFile. (Default)

FlushEachLine

(boolean) Whether the log buffer should be flushed after each line, or flushed after 20 lines. Choose from:

VALUE | DESCRIPTION
true | Force the installer to flush the log buffer after each line.
false | Flush the log buffer after 20 lines. (Default)

Returns

(boolean) Returns true if the action was successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumClients

table MSI.EnumClients (

string ComponentGUID )

Description

Calls the MsiEnumClients function to get an enumerated table of clients for a given installed component.

Parameters

ComponentGUID

(string) The identifier (GUID) of the component whose clients you want to enumerate. This string must be an identifier string enclosed in curly braces, for example: "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}".

Returns

(table) Returns a numerically indexed table of product codes for the given component. If this action fails, or no features are found, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumComponents

table MSI.EnumComponents (

)

Description

Calls the MsiEnumComponents function to get an enumerated table of the installed components for all products.

Parameters

None.

Returns

(table) Returns a numerically indexed table of component GUIDs for all products. If this action fails, or no components are installed, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumFeatures

table MSI.EnumFeatures (

string ProductCode )

Description

Calls the MsiEnumFeatures function to get an enumerated table of the published features for a given product.

Parameters

ProductCode

(string) The "product code" of the product whose features you want to enumerate. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Returns

(table) Returns a numerically indexed table of tables containing the indexes below. If this action fails, or no features are found, nil is returned.

KEY | TYPE | DESCRIPTION
Feature | string | The feature ID.
ParentFeature | string | The parent feature ID.

You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumPatches

table MSI.EnumPatches (

string ProductCode )

Description

Calls the MsiEnumPatches function to enumerate all of the patches that have been applied to a product, returning the patch code GUIDs for each patch that has been applied, and a list of transforms from each patch that apply to the product.

Note: Patches may have many transforms only some of which are applicable to a particular product.

Parameters

ProductCode

(string) The "product code" of the product whose patches you want to enumerate. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Returns

(table) Returns a numerically indexed table of tables containing the indexes below. If this action fails, or no patches are found, nil is returned.

KEY | TYPE | DESCRIPTION
PatchCode | string | The patch code GUID.
TransformList | string | The list of transforms in the patch that are applicable to the product. These are returned in the same format as the value of the TRANSFORMS property (a semicolon ';' delimited string).

You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumProducts

table MSI.EnumProducts (

)

Description

Calls the MsiEnumProducts function to get an enumerated table of all the products currently advertised or installed. Both per-user and per-machine installations and advertisements are enumerated.

Parameters

None.

Returns

(table) Returns a numerically indexed table of product codes. If this action fails, or no products are installed, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.EnumRelatedProducts

table MSI.EnumRelatedProducts (

string UpgradeCode )

Description

Calls the MsiEnumRelatedProducts function to get an enumerated table of products with a specified upgrade code. This function lists the currently installed and advertised products that have the specified UpgradeCode property in their Property table.

Parameters

UpgradeCode

(string) The upgrade code of related products to enumerate. This string must be an identifier string enclosed in curly braces, for example: "{07F11339-6660-4CEC-9E09-BB2FEA780929}".

Returns

(table) Returns a numerically indexed table of product codes. If this action fails, or no products are installed, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetComponentPath

table MSI.GetComponentPath (

string ProductCode,

string ComponentGUID )

Description

Calls the MsiGetComponentPath function to get the full path to an installed component. If the key path for the component is a registry key then the registry key is returned.

Parameters

ProductCode

(string) The "product code" of the client product. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

ComponentGUID

(string) The identifier (GUID) of the component to be located. This string must be an identifier string enclosed in curly braces, for example: "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}".

Returns

(table) Returns nil if the call fails or a table if successful with the following indexes:

InstallState

(number) The install state of the component represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_NOTUSED | -7 | The component being requested is disabled on the computer.
INSTALLSTATE_SOURCEABSENT | -4 | The component source is inaccessible.
INSTALLSTATE_INVALIDARG | -2 | One of the function parameters is invalid.
INSTALLSTATE_UNKNOWN | -1 | The product code or component identifier is unknown.
INSTALLSTATE_ABSENT | 2 | The component is not installed.
INSTALLSTATE_LOCAL | 3 | The component is installed locally.
INSTALLSTATE_SOURCE | 4 | The component is installed to run from source.

ComponentPath

(string) The path to the component. If there was an error getting the component path (i.e. InstallState returns INSTALLSTATE_UNKNOWN) then this table value will be nil.

If the component is a registry key, the registry roots are represented numerically. If this is a registry subkey path, there is a backslash at the end of the Key Path. If this is a registry value key path, there is no backslash at the end. For example, a registry path on a 32-bit operating system of HKEY_CURRENT_USER\SOFTWARE\Microsoft is returned as "01:\SOFTWARE\Microsoft\". The registry roots returned on 32-bit operating systems are defined as shown in the table below.

Note: On 64-bit operating systems, a value of 20 is added to the numerical registry roots in this table to distinguish them from registry key paths on 32-bit operating systems. For example, a registry key path of HKEY_CURRENT_USER\SOFTWARE\Microsoft is returned as "21:\SOFTWARE\Microsoft\", if the component path is a registry key on a 64-bit operating system.

ROOT | VALUE
HKEY_CLASSES_ROOT | 00
HKEY_CURRENT_USER | 01
HKEY_LOCAL_MACHINE | 02
HKEY_USERS | 03

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetFeatureInfo

table MSI.GetFeatureInfo (

number Handle,

string FeatureID,

number Attributes )

Description

Calls the MsiGetFeatureInfo function to get descriptive information for a feature.

Parameters

Handle

(number) The "handle" to the product that owns the feature. You can use the MSI.OpenProduct action to get the product handle.

FeatureID

(string) The identifier of the feature whose information you want.

Attributes

(number) The attributes you want to get. Use the plus sign ("+") to combine values. Choose from one or more of the following:
For more information about these flags, see the Feature Table topic in the MSDN.

CONSTANT | VALUE
INSTALLFEATUREATTRIBUTE_FAVORLOCAL | 1
INSTALLFEATUREATTRIBUTE_FAVORSOURCE | 2
INSTALLFEATUREATTRIBUTE_FOLLOWPARENT | 4
INSTALLFEATUREATTRIBUTE_FAVORADVERTISE | 8
INSTALLFEATUREATTRIBUTE_DISALLOWADVERTISE | 16
INSTALLFEATUREATTRIBUTE_NOUNSUPPORTEDADVERTISE | 32

Returns

(table) Returns a table indexed by the following values.

KEY | TYPE | DESCRIPTION
Title | string | The localized name of the feature.
Description | string | The localized description of the feature.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetFeatureUsage

table MSI.GetFeatureUsage (

string ProductCode,

string FeatureID )

Description

Calls the MsiGetFeatureUsage function to get the usage metrics for a product feature.

Parameters

ProductCode

(string) The "product code" of the product containing the feature. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

FeatureID

(string) The identifier of the feature whose metrics you want.

Returns

(table) Returns a table indexed by the following values. If this action fails or an error occurs, nil is returned:

KEY | TYPE | DESCRIPTION
UsageCount | number | The number of times the feature has been used.
Day | number | The day of the month the feature was last used (1-31).
Month | number | The month the feature was last used (1 = January, 2 = February etc.).
Year | number | The year the feature was last used.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetFileVersion

table MSI.GetFileVersion (

string FilePath )

Description

Calls the MsiGetFileVersion function to get the version and language strings in the format that the installer expects to find them in the database. This action is used to read version resource information from PE files (.exe, dll).

Note: This action will not work on Windows Installer files (.msi).

Parameters

FilePath

(string) The full path to the file whose version/language information you want.

Returns

(table) Returns a table indexed by the following values:

KEY | TYPE | DESCRIPTION
Version | string | The file version.
Language | string | The file language.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetMSIVersion

string MSI.GetMSIVersion (

)

Description

Gets the version of the Windows Installer that is installed on the user's system.

Parameters

None.

Returns

(string) A string containing the version number of the Windows Installer that is currently installed. If an error occurs, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetPatchInfo

string MSI.GetPatchInfo (

string PatchCode,

string Attribute )

Description

Calls the MsiGetPatchInfo function to get information about a patch.

Parameters

PatchCode

(string) The "patch code" for the patch package whose information you want. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Attribute

(string) The patch attribute to be retrieved. For example, for the local cached package you would use "INSTALLPROPERTY_LOCALPACKAGE".

Returns

(string) A string containing the value of the specified attribute. If this action fails, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetProductCode

string MSI.GetProductCode (

string ComponentGUID )

Description

Calls the MsiGetProductCode function to get the product code of an application by using the component GUID of an installed or advertised component of the application. During initialization, an application must determine under which product code it has been installed or advertised.

Parameters

ComponentGUID

(string) The identifier (GUID) of the component that has been installed by the application. This string must be an identifier string enclosed in curly braces, for example: "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}". This will be typically the component containing the executable file of the application.

Returns

(string) A string containing the product code based on the component GUID. If this action fails, a blank string (i.e. "") will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetProductInfo

string MSI.GetProductInfo (

string ProductCode,

string Property )

Description

Calls the MsiGetProductInfo function to get product information for published and installed products given a specified property.

Parameters

ProductCode

(string) The "product code" of the product whose information you want. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Property

(string) The property containing the value you want. Some properties can only be retrieved if they have been set. You can use the available properties listed below, or one that you've previously set yourself.

The following properties can only be retrieved from applications that are installed:

Note: For more information about the properties listed below, see the Property Reference topic in the online MSDN.

PROPERTY | DESCRIPTION
"HelpLink" | The support link. For more information, see the ARPHELPLINK property.
"HelpTelephone" | The support telephone. For more information, see the ARPHELPTELEPHONE property.
"InstallDate" | The installation date.
"InstalledProductName" | The installed product name. For more information, see the ProductName property.
"InstallLocation" | The installation location. For more information, see the ARPINSTALLLOCATION property.
"InstallSource" | The installation source. For more information, see the SourceDir property.
"LocalPackage" | The local cached package.
"Publisher" | The publisher. For more information, see the Manufacturer property.
"URLInfoAbout" | The URL information. For more information, see the ARPURLINFOABOUT property.
"URLUpdateInfo" | The URL update information. For more information, see the ARPURLUPDATEINFO property.
"VersionMinor" | The minor product version derived from the ProductVersion property.
"VersionMajor" | The major product version derived from the ProductVersion property.
"VersionString" | The product version. For more information, see the ProductVersion property.
"ProductID" | The product identifier for the product. For more information, see the ProductID property.
"RegCompany" | The company registered to use this product.
"RegOwner" | The owner registered to use this product.

The following properties can be retrieved from applications that are advertised or installed:

PROPERTY | DESCRIPTION
"InstanceType" | A missing value or a value of "0" (zero) indicates a normal product installation. A value of "1" (one) indicates a product installed using a multiple instance transform and the MSINEWINSTANCE property. Available with the installer running Windows Server 2003 family or Windows XP SP1. For more information see the MSDN article: Installing Multiple Instances of Products and Patches.
"Transforms" | The transforms.
"Language" | The product language.
"ProductName" | The product name. For more information, see the ProductName property.
"AssignmentType" | Returns "0" (zero) if the product is advertised or installed per-user. Returns "1" (one) if the product is advertised or installed per-machine for all users.
"PackageCode" | The identifier of the package this product was installed from.
"Version" | The product version derived from the ProductVersion property.
"ProductIcon" | The primary icon for the package. For more information, see the ARPPRODUCTICON property.
"PackageName" | The name of the original installation package.
"AuthorizedLUAApp" | A returned value of one (1) indicates a product that can be serviced by non-administrators using User Account Control (UAC) Patching. A missing value or returned value of 0 (zero) indicates that least-privilege patching is not enabled. Available in Windows Installer 3.0 or later.

Returns

(string) A string containing the value of the specified property. If this action fails, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetProductProperty

string MSI.GetProductProperty (

number Handle,

string Property )

Description

Calls the MsiGetProductProperty function to retrieve a product property. These are the properties in the product database.

Parameters

Handle

(number) The "handle" to the product obtained from calling the MSI.OpenProduct action.

Property

(string) The property whose value you want. This value is case-sensitive.

Returns

(string) A string containing the value of the specified property. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetShortcutTarget

table MSI.GetShortcutTarget (

string ShortcutTarget )

Description

Calls the MsiGetShortcutTarget function to examine a shortcut and get its product, feature name, and component if available.

Parameters

ShortcutTarget

(string) The full path to the shortcut to examine.

Returns

(table) Returns a table indexed by the following values. If this action fails or an error occurs, nil is returned:

KEY | TYPE | DESCRIPTION
ProductCode | string | A GUID for the product code of the shortcut.
FeatureId | string | The feature name of the shortcut.
ComponentCode | string | A GUID of the component code.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.GetUserInfo

table MSI.GetUserInfo (

string ProductCode )

Description

Calls the MsiGetUserInfo function to get the registered user information for an installed product.

Parameters

ProductCode

(string) The "product code" of the product to be queried. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Returns

(table) Returns nil if the call fails or a table if successful with the following indexes:

UserInfoState

(number) The state of the user info represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
USERINFOSTATE_MOREDATA | -3 | A buffer is too small to hold the requested data.
USERINFOSTATE_INVALIDARG | -2 | One of the function parameters was invalid.
USERINFOSTATE_UNKNOWN | -1 | The product code does not identify a known product.
USERINFOSTATE_ABSENT | 0 | Some or all of the user information is absent.
USERINFOSTATE_PRESENT | 1 | The function completed successfully.

UserName

(string) The name of the registered user. If the information could not be retrieved, an empty string ("") is returned.

CompanyName

(string) The company name of the registered user. If the information could not be retrieved, an empty string ("") is returned.

SerialNumber

(string) The serial number of the product. If the information could not be retrieved, an empty string ("") is returned.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.InstallMissingComponent

boolean MSI.InstallMissingComponent (

string ProductCode,

string ComponentGUID,

number InstallState )

Description

Calls the MsiInstallMissingComponent function to install a component that is unexpectedly missing.

Parameters

ProductCode

(string) The "product code" of the product that owns the component to be installed. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

ComponentGUID

(string) The identifier (GUID) of the component to be installed. This string must be an identifier string enclosed in curly braces, for example: "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}".

InstallState

(number) The way the component should be installed. Choose from one of the following:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_LOCAL | 3 | The component should be locally installed.
INSTALLSTATE_SOURCE | 4 | The component should be installed to run from the source.
INSTALLSTATE_DEFAULT | 5 | The component should be installed according to the installer defaults.

Returns

(boolean) Returns true if the action was successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.InstallMissingFile

boolean MSI.InstallMissingFile (

string ProductCode,

string File )

Description

Calls the MsiInstallMissingFile function to install a file that is unexpectedly missing.

Parameters

ProductCode

(string) The "product code" of the product that owns the file to be installed. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

File

(string) The identifier of the file to be installed.

Returns

(boolean) Returns true if the action was successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.InstallProduct

boolean MSI.InstallProduct (

string PackagePath,

string CommandLine)

Description

Calls the MsiInstallProduct function to install or uninstall a product.

Parameters

PackagePath

(string) The full path and filename of the package to install.

CommandLine

(string) The command line property settings to pass to the package. This string should be a list in the format: "Property=Setting Property=Setting". To perform an administrative installation, include "ACTION=ADMIN". You can completely remove a product using "REMOVE=ALL", or install a product using "ACTION=INSTALL."

Returns

(boolean) True if the action completely successfully, and false if it did not or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.LocateComponent

table MSI.LocateComponent (

string ComponentGUID )

Description

Calls the MsiLocateComponent function to get the full path to an installed component without a product code. This function attempts to determine the product using MsiGetProductCode, but is not guaranteed to find the correct product for the caller. The MSI.GetComponentPath action should always be called when possible.

Parameters

ComponentGUID

(string) The identifier (GUID) of the component to be located. This string must be an identifier string enclosed in curly braces, for example: "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}".

Returns

(table) Returns nil if the call fails or a table if successful with the following indexes:

InstallState

(number) The install state of the component represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_NOTUSED | -7 | The component being requested is disabled on the computer.
INSTALLSTATE_SOURCEABSENT | -4 | The component source is inaccessible.
INSTALLSTATE_MOREDATA | -3 | The buffer provided was too small.
INSTALLSTATE_INVALIDARG | -2 | One of the function parameters is invalid.
INSTALLSTATE_UNKNOWN | -1 | The product code or component ID is unknown.
INSTALLSTATE_ABSENT | 2 | The component is not installed.
INSTALLSTATE_LOCAL | 3 | The component is installed locally.
INSTALLSTATE_SOURCE | 4 | The component is installed to run from source.

ComponentPath

(string) The path to the component. If there was an error getting the component path (i.e. InstallState returns INSTALLSTATE_UNKNOWN) then this table value will be nil.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.OpenPackage

number MSI.OpenPackage (

string PackagePath )

Description

Calls the MsiOpenPackage function to open a package for use with the actions that access the product database. You must call the MSI.CloseHandle action with the handle when it is no longer needed.

Parameters

PackagePath

(string) The full path to the package whose handle you want.

Returns

(number) The handle to the MSI package. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.OpenProduct

number MSI.OpenProduct (

string ProductCode )

Description

Calls the MsiOpenProduct function to open a product for use with the actions that access the product database. You must call the MSI.CloseHandle action with the handle when it is no longer needed.

Parameters

ProductCode

(string) The "product code" of the product you want to open. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Returns

(number) The handle to the MSI product. If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.QueryFeatureState

number MSI.QueryFeatureState (

string ProductCode,

string Feature )

Description

Calls the MsiQueryFeatureState function to get the installed state for a product feature.

Parameters

ProductCode

(string) The "product code" of the product containing the feature. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Feature

(string) The feature whose installed state you want.

Returns

(number) The installed state of the feature represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_INVALIDARG | -2 | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | -1 | The product code or feature ID is unknown.
INSTALLSTATE_ADVERTISED | 1 | The feature is advertised.
INSTALLSTATE_ABSENT | 2 | The feature is not installed.
INSTALLSTATE_LOCAL | 3 | The feature is installed locally.
INSTALLSTATE_SOURCE | 4 | The feature is installed to run from source.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.QueryProductState

number MSI.QueryProductState (

string ProductCode )

Description

Calls the MsiQueryProductState function to get the installed state for a product.

Parameters

ProductCode

(string) The "product code" of the product whose state you want. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

Returns

(number) The installed state of the product represented by one of the following values:

CONSTANT | VALUE | DESCRIPTION
INSTALLSTATE_INVALIDARG | -2 | An invalid parameter was passed to the function.
INSTALLSTATE_UNKNOWN | -1 | The product is neither advertised or installed.
INSTALLSTATE_ADVERTISED | 1 | The product is advertised but not installed.
INSTALLSTATE_ABSENT | 2 | The product is installed for a different user.
INSTALLSTATE_DEFAULT | 5 | The product is installed for the current user.

You can use Application.GetLastError to determine whether this action failed, and why.


MSI.ReinstallFeature

boolean MSI.ReinstallFeature (

string ProductCode,

string FeatureID,

number ReinstallMode )

Description

Calls the MsiReinstallFeature function to reinstall a feature.

Parameters

ProductCode

(string) The "product code" of the product that contains the feature to be reinstalled. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

FeatureID

(string) The identifier of the feature to be reinstalled. The parent feature or child feature of the specified feature is not reinstalled. To reinstall the parent or child feature, you must call the MSI.ReinstallFeature action for each separately, or use the MSI.ReinstallProduct action.

ReinstallMode

(number) The reinstall mode. Use the plus sign ("+") to combine values. Choose from one or more of the following:

CONSTANT | VALUE | DESCRIPTION
REINSTALLMODE_FILEMISSING | 2 | Reinstall only if the file is missing.
REINSTALLMODE_FILEOLDERVERSION | 4 | Reinstall if the file is missing or is an older version.
REINSTALLMODE_FILEEQUALVERSION | 8 | Reinstall if the file is missing, or is an equal or older version.
REINSTALLMODE_FILEEXACT | 16 | Reinstall if the file is missing or is a different version.
REINSTALLMODE_FILEVERIFY | 32 | Verify the checksum values and reinstall the file if they are missing or corrupt. This flag only repairs files that have msidbFileAttributesChecksum in the Attributes column of the File table.
REINSTALLMODE_FILEREPLACE | 64 | Force all files to be reinstalled, regardless of checksum or version.
REINSTALLMODE_MACHINEDATA | 128 | Rewrite all required registry entries from the Registry Table that go to the HKEY_LOCAL_MACHINE or HKEY_CLASSES_ROOT registry hive. Rewrite all information from the Class Table, Verb Table, PublishComponent Table, ProgID Table, MIMET Table, Icon Table, Extension Table, and AppID Table regardless of machine or user assignment. Reinstall all qualified components. When reinstalling an application, this option runs the RegisterTypeLibraries and InstallODBC actions.
REINSTALLMODE_USERDATA | 256 | Rewrite all required registry entries from the Registry Table that go to the HKEY_CURRENT_USER or HKEY_USERS registry hive.
REINSTALLMODE_SHORTCUT | 512 | Reinstall all shortcuts and re-cache all icons overwriting any existing shortcuts and icons.
REINSTALLMODE_PACKAGE | 1024 | Use to run from the source package and re-cache the local package. Do not use for the first installation of an application or feature.

Returns

(boolean) Returns true if the action was successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.ReinstallProduct

boolean MSI.ReinstallProduct (

string ProductCode,

number ReinstallMode )

Description

Calls the MsiReinstallProduct function to reinstall a product.

Parameters

ProductCode

(string) The "product code" of the product to be reinstalled. This string must be an identifier string enclosed in curly braces, for example: "{78B82B0B-9AD9-40C0-B994-F72C21B52723}".

ReinstallMode

(number) The reinstall mode. Use the plus sign ("+") to combine values. Choose from one or more of the following:

CONSTANT | VALUE | DESCRIPTION
REINSTALLMODE_FILEMISSING | 2 | Reinstall only if the file is missing.
REINSTALLMODE_FILEOLDERVERSION | 4 | Reinstall if the file is missing or is an older version.
REINSTALLMODE_FILEEQUALVERSION | 8 | Reinstall if the file is missing, or is an equal or older version.
REINSTALLMODE_FILEEXACT | 16 | Reinstall if the file is missing or is a different version.
REINSTALLMODE_FILEVERIFY | 32 | Verify the checksum values and reinstall the file if they are missing or corrupt. This flag only repairs files that have msidbFileAttributesChecksum in the Attributes column of the File table.
REINSTALLMODE_FILEREPLACE | 64 | Force all files to be reinstalled, regardless of checksum or version.
REINSTALLMODE_MACHINEDATA | 128 | Rewrite all required registry entries from the Registry Table that go to the HKEY_LOCAL_MACHINE or HKEY_CLASSES_ROOT registry hive. Rewrite all information from the Class Table, Verb Table, PublishComponent Table, ProgID Table, MIMET Table, Icon Table, Extension Table, and AppID Table regardless of machine or user assignment. Reinstall all qualified components. When reinstalling an application, this option runs the RegisterTypeLibraries and InstallODBC actions.
REINSTALLMODE_USERDATA | 256 | Rewrite all required registry entries from the Registry Table that go to the HKEY_CURRENT_USER or HKEY_USERS registry hive.
REINSTALLMODE_SHORTCUT | 512 | Reinstall all shortcuts and re-cache all icons overwriting any existing shortcuts and icons.
REINSTALLMODE_PACKAGE | 1024 | Use to run from the source package and re-cache the local package. Do not use for the first installation of an application or feature.

Returns

(boolean) Returns true if the action was successful, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.RunMsiexec

number MSI.RunMsiexec (

string Arguments,

boolean WaitForReturn = true )

Description

Runs the Windows Installer program "msiexec.exe" with the specified arguments.

Parameters

Arguments

(string) The arguments you want to pass to "msiexec.exe". For example, "-i \""C:\Temp\Example.msi"\" PROPERTY=VALUE"

WaitForReturn

(boolean) Whether the application will wait until the executable has exited before continuing:

VALUE | DESCRIPTION
true | Wait. (Default)
false | Don't wait.

Note: This parameter must be set to true if you want to receive a process return code.

Returns

(number) The process return code if the WaitForReturn parameter is set to true. If WaitForReturn is set to false 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: On Windows Vista or later, if this action fails due to requiring elevation, error code 1045 is returned.

Note: If the specified process has not terminated, the termination status returned is STILL_ACTIVE. If the process has terminated, the termination status returned may be one of the following:

The exit value specified in the ExitProcess or TerminateProcess function.
The return value from the main or WinMain function of the process.
The exception value for an unhandled exception that caused the process to terminate.

MSDN Online: Command-Line Options


MSI.SetInternalUI

table MSI.SetInternalUI (

number UILevel,

number WindowHandle = nil )

Description

Calls the MsiSetInternalUI function to enable the installer's internal user interface. Then this user interface is used for all subsequent calls to user-interface-generating installer functions in this process. This action is usually called before calling the MSI.InstallProduct action.

Parameters

UILevel

(number) The user interface level to set. Some values can be combined with others. In that case, use the plus sign ("+") to combine values. Choose from:

CONSTANT | VALUE | DESCRIPTION
INSTALLUILEVEL_NOCHANGE | 0 | No change in the UI level. However, if WindowHandle is not nil, the parent window can change.
INSTALLUILEVEL_DEFAULT | 1 | The installer chooses an appropriate user interface level.
INSTALLUILEVEL_NONE | 2 | Completely silent installation.
INSTALLUILEVEL_BASIC | 3 | Simple progress and error handling.
INSTALLUILEVEL_REDUCED | 4 | Authored user interface with wizard dialog boxes suppressed.
INSTALLUILEVEL_FULL | 5 | Authored user interface with wizards, progress, and errors.
INSTALLUILEVEL_HIDECANCEL | 32 | If combined with the INSTALLUILEVEL_BASIC value, the installer shows simple progress dialog boxes but does not display a Cancel button on the dialog. This prevents users from canceling the install.
INSTALLUILEVEL_PROGRESSONLY | 64 | If combined with the INSTALLUILEVEL_BASIC value, the installer shows simple progress dialog boxes but does not display any modal dialog boxes or error dialog boxes.
INSTALLUILEVEL_ENDDIALOG | 128 | If combined with any above value, the installer displays a modal dialog box at the end of a successful installation or if there has been an error. No dialog box is displayed if the user cancels.
INSTALLUILEVEL_SOURCERESONLY | 256 | If this value is combined with the INSTALLUILEVEL_NONE value, the installer displays only the dialog boxes used for source resolution. No other dialog boxes are shown. This value has no effect if the UI level is not INSTALLUILEVEL_NONE. It is used with an external user interface designed to handle all of the UI except for source resolution. In this case, the installer handles source resolution.

WindowHandle

(number) A windows handle that becomes the owner of any user interface created. If this parameter is nil, the owner of the user interface does not change. You can use the Application.GetWndHandle action to get a handle to the application's main window.

Returns

(table) Returns nil if the call fails or a table if successful with the following indexes:

KEY | TYPE | DESCRIPTION
PreviousInterface | number | The previous user interface level.
PreviousWindowHandle | number | The previous window handle of the owner process. If WindowHandle was passed in as nil or not specified, this value will be nil.

If the action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.


MSI.VerifyPackage

boolean MSI.VerifyPackage (

string PackagePath )

Description

Calls the MsiVerifyPackage function to verify that the given file is an installation package.

Parameters

PackagePath

(string) The full path and filename of the package.

Returns

(boolean) Returns true if the file is a package, or false if it is not or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.


ODBC.ConfigDataSource

ODBC.ConfigDataSource (

string DriverDescription,

string Attributes,

number Request )

Description

Configures an ODBC data source.

Parameters

DriverDescription

(string) A description of the driver, for example "Microsoft Access Driver (*.mdb)".

Attributes

(string) A string of attributes in 'keyword = value' pairs. Each attribute is separated by "\\0".

For example: "DSN=QandA\\0DBQ=J:\\DATABASE\\QandA.mdb\\0FIL=MS Access;\\0DESCRIPTION=Questions and Answers Database\\0DRIVERID=25\\0UID=\\0\\0"

Request

(number) The type of action that will be performed. Choose from:

CONSTANT | VALUE | DESCRIPTION
ODBC_ADD_DSN | 1 | Add a new user data source.
ODBC_CONFIG_DSN | 2 | Configure (modify) an existing user data source.
ODBC_REMOVE_DSN | 3 | Remove an existing user data source.
ODBC_ADD_SYS_DSN | 4 | Add a new system data source.
ODBC_CONFIG_SYS_DSN | 5 | Modify an existing system data source.
ODBC_REMOVE_SYS_DSN | 6 | Remove an existing system data source.
ODBC_REMOVE_DEFAULT_DSN | 7 | Remove the default data source specification section from the system information.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


ODBC.InstallDriver

string ODBC.InstallDriver (

string Driver )

Description

Installs an ODBC driver. This is accomplished by adding information about the driver to the Odbcinst.ini entry in the system information and incrementing the driver's UsageCount by 1.

Note: This action does not actually copy any files. You must also copy the driver's files to the target directory.

Parameters

Driver

(string) A string containing the driver description and 'name = value' pairs describing the driver. Each attribute is separated by "\\0".

For example: "Microsoft Access Driver(*.mdb)\\0Driver=odbcjt32.dll\\0Setup=odbcjt32.dll\\0FileUsage=1\\0FileExtns=*.mdb\\0APILevel=1\\0ConnectFunctions=YYN\\0DriverODBCVer=02.50\\0SQLLevel=0\\0\\0"

Returns

(string) The path of the target directory where the driver was installed. If the driver has not previously been installed, this path will be the same as that specified in the Driver parameter. If the driver was previously installed, this path will be the path to the previous installation. If an error occurs, a blank string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


ODBC.InstallManager

string ODBC.InstallManager (

)

Description

Returns the path of the target directory for the installation of the ODBC core components and increments the component usage count in the system information.

Note: You must actually copy the Driver Manager's files to the target directory.

If a version of the Driver Manager already exists but the component usage count for the driver does not exist, the new component usage count value is set to 2.

Parameters

None.

Returns

(string) The path of the target directory of the installation. If an error occurs, a blank string is returned (""). You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


ODBC.UninstallDriver

number ODBC.UninstallDriver (

string Driver,

boolean RemoveDSN = false )

Description

Uninstalls the driver and returns the usage count after the action is done. This is accomplished by removing information about the driver from the Odbcinst.ini entry in the system information. This action wraps the SQLRemoveDriver function of the Windows API.

Note: This action does not actually remove any files. If you would like the driver file removed, you must remove it using actions. However generally it is dangerous to remove the drivers from the user's system if there is potential that they are shared.

Parameters

Driver

(string) A string containing the name of the driver as registered in the Odbcinst.ini key of the system information.

For example: "Microsoft Access Driver (*.mdb)"

RemoveDSN

(boolean) Whether or not to remove DSN's associated with the driver.

VALUE | DESCRIPTION
true | Remove DSNs associated with the driver specified in the Driver parameter.
false | Do not remove DSNs associated with the driver specified in the Driver parameter. (Default)

Returns

(number) The usage count of the driver after this function has been called. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


ODBC.UninstallManager

number ODBC.UninstallManager (

)

Description

Uninstalls the driver manager, and returns its usage count after it's done. This is accomplished by removing information about the ODBC core components from the Odbcinst.ini entry in the system information. This action wraps the RemoveDriverManager function of the Windows API.

Note: This action does not actually remove any files. If you would like the files removed, you must remove them using actions. However generally driver manager files should not be removed from the user's system because these files may be used by other applications that have not incremented the file usage count.

Parameters

None.

Returns

(number) The usage count of the Driver Manager after this function has been called. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Registry.CreateKey

Registry.CreateKey (

number MainKey,

string SubKey )

Description

Creates a "key" in the user's Registry.

Note: Some locations in the Windows Registry cannot be modified in order to protect the operating system. This is something to consider when choosing a location to write information.

Parameters

MainKey

(number) The main or "root" key where you want to create the key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key to create.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.DeleteKey

Registry.DeleteKey (

number MainKey,

string SubKey )

Description

Deletes a "key" from the user's Registry.

Parameters

MainKey

(number) The main or "root" key where you want to delete the key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key to delete.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.DeleteValue

Registry.DeleteValue (

number MainKey,

string SubKey,

string Value )

Description

Deletes a "value" from the user's Registry.

Parameters

MainKey

(number) The main or "root" key where the value can be found. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key that contains the value.

Value

(string) The value to delete.

Note: To specify the "(Default)" value, use an empty string "" as the value name. Deleting the "(Default)" value results in the removal of the key and all of its values.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Registry.DoesKeyExist

boolean Registry.DoesKeyExist (

number MainKey,

string SubKey )

Description

Determines whether or not a particular Registry key exists and returns either true or false.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key to check for existence.

Returns

(boolean) True if the sub key exists, or false if it doesn't or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Registry.GetAccess

boolean Registry.GetAccess (

number MainKey,

string SubKey,

number Rights = ACCESS_ALL )

Description

Checks to see if a Registry key has specific access rights and returns either true or false.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key to check for access rights.

Rights

(number) The access rights to check. Choose from:

CONSTANT | VALUE | DESCRIPTION
ACCESS_READ | 131097 | The Registry key contents can be read.
ACCESS_WRITE | 131078 | The Registry key can be written to.
ACCESS_ENUMERATE | 8 | The Registry key contents can be enumerated.
ACCESS_ALL | 98103 | The key has full access rights. (Default)

Returns

(boolean) True if the key has the specified access rights and false if it doesn't or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Registry.GetKeyNames

table Registry.GetKeyNames (

number MainKey,

string SubKey )

Description

Returns a table containing the names of all of the sub keys for a particular key.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The key whose sub key names you want.

Returns

(table) A table containing the names of all of the sub keys under the specified key. If there are no key names or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Registry.GetValue

string Registry.GetValue (

number MainKey,

string SubKey,

string Value,

boolean AutoExpand = true )

Description

Returns a specific Registry value's data.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key containing the value.

Value

(string) The value whose data you want.

Note: To get the "(Default)" value's data, use an empty string "" as the value name.

AutoExpand

(boolean) Whether to expand any environment variables in the data before it is returned. This option is used when retrieving a value whose type is REG_EXPAND_SZ:

VALUE | DESCRIPTION
true | Expand environment variables. (Default)
false | Don't expand environment variables.

Returns

(string) The data contained within the Registry value. If the action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: For values of type REG_BINARY, the returned value will be a string of hex values separated by spaces. For values of type REG_MULTI_SZ, a string will be returned where each registry entry string is separated by a "|" character.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Registry.GetValueNames

table Registry.GetValueNames (

number MainKey,

string SubKey )

Description

Returns the names of all of the values within a specific sub key.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key whose value names you want.

Returns

(table) A table containing the names of all the values in the sub key. If the sub key contains no values or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Registry.GetValueType

number Registry.GetValueType (

number MainKey,

string SubKey,

string Value )

Description

Returns a Registry value's type.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key containing the value.

Value

(string) The value whose type you want.

Note: To use the "(Default)" value, use an empty string "" as the value name.

Returns

(number) A numeric constant that corresponds to the Registry value's type:

CONSTANT | VALUE | DESCRIPTION
REG_NONE | 0 | No defined value type.
REG_SZ | 1 | A null-terminated string. ("SZ" is short for "string, zero-terminated.")
REG_EXPAND_SZ | 2 | A null-terminated string that contains environment variables which are to be expanded whenever the Registry value is accessed.
REG_BINARY | 3 | Raw binary data.
REG_DWORD | 4 | A 32-bit number.
REG_DWORD_LITTLE_ENDIAN | 4 | A 32-bit number in little-endian format. This is the same as REG_DWORD.
REG_DWORD_BIG_ENDIAN | 5 | A 32-bit number in big-endian format.
REG_LINK | 6 | A Unicode symbolic link. Used internally; applications should not use this type.
REG_MULTI_SZ | 7 | An array of null-terminated strings, each one terminated by two null characters.
REG_RESOURCE_LIST | 8 | A device-driver resource list.
REG_FULL_RESOURCE_DESCRIPTOR | 9 | A list of hardware resources.
REG_RESOURCE_REQUIREMENTS_LIST | 10 | A list of resources required by a driver.

If the action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Registry.SetValue

Registry.SetValue (

number MainKey,

string SubKey,

string Value,

string Data,

number Type = REG_SZ )

Description

Sets the data of a specific Registry value.

Parameters

MainKey

(number) The main or "root" key containing the sub key. Choose from:

CONSTANT | VALUE
HKEY_CLASSES_ROOT | 0
HKEY_CURRENT_CONFIG | 1
HKEY_CURRENT_USER | 2
HKEY_LOCAL_MACHINE | 3
HKEY_USERS | 4

SubKey

(string) The sub key containing the value.

Value

(string) The value whose data you want to set.

Note: To set the "(Default)" value, use an empty string "" as the value name.

Data

(string) The data you want to assign to the value.

Type

(number) The type of data you want to assign:

CONSTANT | VALUE | DESCRIPTION
REG_SZ | 1 | A null-terminated string. ("SZ" is short for "string, zero-terminated.")
REG_EXPAND_SZ | 2 | A null-terminated string that contains environment variables which are to be expanded whenever the Registry value is accessed.
REG_BINARY | 3 | Raw binary data. Setup Factory requires this data be passed as a string of hex values separated by single spaces. For example, 2C 00 00
REG_DWORD | 4 | A 32-bit number.
REG_MULTI_SZ | 7 | An array of null-terminated strings, each one terminated by two null characters. When storing multiple string values in one Registry value, Setup Factory requires that each string be separated by a "|" character. For example \Hey|\You.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.Back

Screen.Back (

)

Description

Moves back one screen in the history of the viewed screens. This action behaves like the back button on a Web Browser.

Note: When this action is called, it will exit the current block of script.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.End

Screen.End (

)

Description

Jumps to the end of the current screen list and starts the next stage in the install.

For example, if you created this action on one of the Before Installing screens, the install would skip any Before Installing screens that follow it and start executing the actions on the On Pre Install actions tab, which is the next install stage.

Note: When this action is called, it will exit the current block of script.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.GetFocus

number Screen.GetFocus (

)

Description

Returns the control ID of the control the currently has focus.

Note: This action will not function correctly if called from the On Preload event.

Parameters

None.

Returns

(number) The control ID of the control on the current screen which has focus. If nothing has focus, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Screen.GetLocalizedString

string Screen.GetLocalizedString (

string StringID )

Description

Gets the text of a string ID in the current language on the current screen.

Parameters

StringID

(string) The screen string ID whose localized text you want to get.

Returns

(string) The localized text of the given screen string ID. If this action fails, a blank string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Screen.GetProperties

table Screen.GetProperties (

)

Description

Gets the properties of the currently displayed screen.

Parameters

None.

Returns

(table) A table containing the following information:

KEY | TYPE | DESCRIPTION
WindowHandle | number | The window handle of the current screen.
ScreenName | string | The name of the current screen.
ScreenType | number | The type of screen (see table below).
Controls | table | A numerically indexed (1-based) table of the controls on the screen. Each table item is itself a table, containing the values outlined below.

Screen Types:

VALUE | SCREEN TYPE
100 | Static Text
105 | Scrolling Text
110 | Select Install Folder
115 | Select Shortcut Folder
120 | Edit Fields
125 | Licence Agreement
130 | Progress Bar
135 | Radio Buttons
140 | Combo Boxes
145 | Select Packages
150 | CheckBoxes
155 | Scrolling Text Progress
160 | ListBox
165 | Buttons
170 | Custom

Controls Table:

KEY | TYPE | DESCRIPTION
WindowHandle | number | The window handle of the current screen. Note: StaticText controls do not have a window handle and will return 0 for this value.
Type | number | The type of control (see table below).
CtrlID | number | The Control ID.

Control Types:

VALUE | SCREEN TYPE
1 | Button
2 | Static Text
3 | Scrolling Text
4 | ComboBox
5 | Radio Button
6 | Edit Field
7 | Progress Bar
8 | Select Package Tree
9 | Category
10 | CheckBox
11 | ListBox
12 | GroupBox

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Screen.Jump

Screen.Jump (

string ScreenName )

Description

Jumps to a specific screen in your install given a screen name.

Note: This action can be used to jump forward or backward in the install, however the target screen must be located in the current screen list. For example, if your current screen is located in the Before Installing list, the target screen must also be located in that list. You cannot just from a Before Installing screen to an After Installing screen.

Note: When this action is called, it will exit the current block of script.

Parameters

ScreenName

(string) The name of the screen you want to jump to.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.Next

Screen.Next (

)

Description

Proceeds to the next screen in the screen list according to the order in the screen manager at design time.

If the current screen is the last screen in the current screen list, the install will move on to the next install stage. For example, if the current screen is the last screen listed in the Before Installing list and this action is called, the next install stage will begin, which are the actions on the On Pre Install actions tab.

Note: When this action is called, it will exit the current block of script.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.Previous

Screen.Previous (

)

Description

Proceeds to the previous screen that is in your screen list according to their order in the screen manager at design time. If the current screen is the first screen, this action will have no effect.

Note: When this action is called, it will exit the current block of script.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.SetFocus

Screen.SetFocus (

number ControlID )

Description

Sets the screen's input focus to the control whose control ID matches the specified id.

Note: You cannot set focus to static controls or controls that are not visible, or disabled.

Parameters

ControlID

(string) The control ID of the control which you want to give focus to.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.SetLocalizedString

Screen.SetLocalizedString (

string StringID,

string Text )

Description

Sets the text of a string ID in the current language on the current screen.

Parameters

StringID

(string) The string ID whose text you want to set.

Text

(string) The text you want you want to display for the string ID.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.SetStartScreen

Screen.SetStartScreen (

string ScreenName )

Description

Sets the first screen that will be displayed in the next screen list that is displayed. This action can be called to affect either the Before Installing or After Installing screens.

Note: The start screen value will be automatically reset back to "" after the next set of screens is displayed.

Parameters

ScreenName

(string) The name of the screen you want to show first in the next screen list that is displayed.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.StartTimer

Screen.StartTimer ( number Interval

)

Description

Starts a timer on the screen. When the timer fires, the screen gets a MSGID_ONTIMER through an On Ctrl Message.

Note: This action will stop any previous timers and restart the timer at the new interval. Timers stop automatically when the screen is left.

Parameters

Interval

(number) The time interval in milliseconds.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Screen.StopTimer

Screen.StopTimer (

)

Description

Stops the timer started by Screen.StartTimer.

Note: The screen's timer is automatically stopped when a different screen is displayed.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Continue

Service.Continue (

string DisplayName,

string KeyName = "" )

Description

Continues a specific service that has been previously paused.

Parameters

DisplayName

(string) The display name of the service that you wish to continue.

KeyName

(string) The key name of the service that you wish to continue.

Note: The key name is only required if no service matches the display name.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Create

Service.Create (

string Filename,

string DisplayName = "Service1",

string KeyName = "",

number ServiceType = SERVICE_WIN32_OWN_PROCESS,

boolean AllowDesktopInteraction = false,

number StartType = SERVICE_DEMAND_START,

number ErrorControl = SERVICE_ERROR_NORMAL,

string LoadOrderGroup = "",

number GroupTag = nil,

table Dependencies = nil,

string ServiceStartName = "",

string Password = "" )

Description

Creates a new service on the local system.

Parameters

Filename

(string) The fully qualified path to the service binary file, with or without arguments.

DisplayName

(string) A string that user interface programs will use to identify the service.

KeyName

(number) A string that names the service to install. The maximum string length is 256 characters to be a valid Windows key name.

Note: The service control manager database preserves the case of the characters, but service name comparisons are always case insensitive. Forward-slash (/) and back-slash (\) are invalid service name characters.

ServiceType

(number) The type of service. This can be one of the following:

CONSTANT | VALUE | DESCRIPTION
SERVICE_WIN32_OWN_PROCESS | 0 | Service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS | 1 | Service that shares a process with other services.
SERVICE_KERNEL_DRIVER | 2 | Driver service.
SERVICE_FILE_SYSTEM_DRIVER | 3 | File system driver service.

AllowDesktopInteraction

(boolean) Whether to allow the service process to interact with the desktop. If set to true, the service must run in the "LocalSystem" account. This can be done by setting the ServiceStartName to "LocalSystem".

StartType

(number) The way in which the service will be started. This can be one of the following:

CONSTANT | VALUE | DESCRIPTION
SERVICE_BOOT_START | 0 | A device driver started by the system loader. This value is valid only for driver services.
SERVICE_SYSTEM_START | 1 | A device driver started by the IoInitSystem function. This value is valid only for driver services.
SERVICE_AUTO_START | 2 | A service started automatically by the service control manager during system startup.
SERVICE_DEMAND_START | 3 | A service started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED | 4 | A service that cannot be started. Attempts to start this service will result in a Windows error.

ErrorControl

(number) The severity of the error if this service fails to start during startup. Can be one of the following:

CONSTANT | VALUE | DESCRIPTION
SERVICE_ERROR_IGNORE | 0 | The startup program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL | 1 | The startup program logs the error and puts up a message box pop-up but continues the startup operation.
SERVICE_ERROR_SEVERE | 2 | The startup program logs the error. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.
SERVICE_ERROR_CRITICAL | 3 | The startup program logs the error, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration.

LoadOrderGroup

(string) The name of the load ordering group of which this service is a member. Enter an empty string "" if it does not belong to a group.

GroupTag

(number) The tag value. This value is unique to the load order group. Tags are only evaluated for driver services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

Dependencies

(table) A numerically indexed table containing the names of services or load order groups that must be loaded before this service can start.

ServiceStartName

(string) A string that names the account under which the service should run. If the service type is SERVICE_WIN32_OWN_PROCESS, use an account name in the form "DomainName\\UserName". The service process will be logged on as this user. If the account belongs to the built-in domain, you can specify ".\\UserName". If this parameter is empty (""), the service create uses the LocalSystem account. If the AllowDesktopInteraction option is set to true, the service must run in the "LocalSystem" account.

Password

(string) The password for the service. Specify an empty string "" if the account has no password or if the service runs in the LocalService, NetworkService, or LocalSystem account. Passwords are ignored for driver services.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Delete

Service.Delete (

string DisplayName,

string KeyName = "" )

Description

Deletes a specific service from the service database on the user's system.

Parameters

DisplayName

(string) The display name of the service that you wish to delete.

KeyName

(string) The key name of the service that you wish to delete.

Note: The key name is only required if no service matches the display name.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Pause

Service.Pause (

string DisplayName,

string KeyName = "" )

Description

Pauses a specific service on the local system.

Parameters

DisplayName

(string) The display name of the service that you wish to pause.

KeyName

(string) The key name of the service that you wish to pause.

Note: The key name is only required if no service matches the display name.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Query

number Service.Query (

string DisplayName,

string KeyName = "" )

Description

Queries the system for the status of a specific service.

Parameters

DisplayName

(string) The display name of the service that you wish to query.

KeyName

(string) The key name of the service that you wish to query.

Returns

(number) A number containing the status of the specific service. Can be one of the following:

CONSTANT | VALUE | DESCRIPTION
SERVICE_NOT_FOUND | 0 | The service was not found.
SERVICE_STOPPED | 1 | The service is not running.
SERVICE_START_PENDING | 2 | The service is starting.
SERVICE_STOP_PENDING | 3 | The service is stopping.
SERVICE_RUNNING | 4 | The service is running.
SERVICE_CONTINUE_PENDING | 5 | The service continue is pending.
SERVICE_PAUSE_PENDING | 6 | The service pause is pending.
SERVICE_PAUSED | 7 | The service is paused.
SERVICE_ERROR | -1 | Returned on error.

You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Service.Start

Service.Start (

string DisplayName,

string KeyName = "",

table Arguments = nil )

Description

Starts a specific service on the user's system.

Parameters

DisplayName

(string) The display name of the service that you wish to start.

KeyName

(string) The key name of the service that you wish to start.

Note: The key name is only required if no service matches the display name.

Arguments

(table) A numerically index table of arguments to be passed to the service when it starts.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Service.Stop

Service.Stop (

string DisplayName,

string KeyName = "",

number WaitTime = 0 )

Description

Stops a specific service on the user's system.

Parameters

DisplayName

(string) The display name of the service that you wish to stop.

KeyName

(string) The key name of the service that you wish to stop.

Note: The key name is only required if no service matches the display name.

WaitTime

(number) The maximum time to wait for the service to stop (in seconds).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


SessionVar.Expand

string SessionVar.Expand (

string Text )

Description

Returns a string containing the contents of the given session variable.

Parameters

Text

(string) A string containing one or more session variables you want to expand.

Note: This string can contain non-session variable text as well.

Returns

(string) A string containing the contents of the given session variable. If an error occurs, a blank string "" will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SessionVar.Get

string SessionVar.Get (

string VariableName )

Description

Returns the unexpanded contents of a session variable.

For example:
If the session variable %MyVar% contains another session variable %MyInsideVar%, using SessionVar.Get will return the string "%MyInsideVar%" and not the expanded contents of %MyInsideVar%. To recursively expand the contents, you would use the SessionVar.Expand action.

Tip: You can tell when a session variable is undefined if the string returned is the same as the string passed in.

Parameters

VariableName

(string) The name of the session variable whose contents you want.

Returns

(string) A string containing the session variable's contents. If an error occurs, the string that was passed in is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SessionVar.Remove

SessionVar.Remove (

string VariableName )

Description

Removes the given session variable from the session variable manager at runtime. This essentially "undefines" the session variable.

Parameters

VariableName

(string) The name of the session variable you want to remove (undefine).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


SessionVar.Set

SessionVar.Set (

string VariableName,

string Value )

Description

Sets the given session variable to the specified value.

Note: Session variables used on screens must be set prior to the screen's displaying and all of its events, such as a previous screen, or project event. Setting a session variable on a screen's event will have no effect on the current screen unless the screen control text is updated using the appropriate Dlg***.SetProperties action.

Parameters

VariableName

(string) The name of the session variable whose value you want to set.

Value

(string) The value you want to set the session variable to.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


SetupData.CalculateRequiredSpace

number SetupData.CalculateRequiredSpace (

function CallbackFunction = nil )

Description

Calculates the amount of disk space needed by the setup at it's current state, with the variables, packages, etc. as they are at the time that the action is called.

Tip: To display the information returned by this action in a formatted way, use String.GetFormattedSize.

Parameters

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the disk space calculation. (You can use this callback function to display the progress of the disk space calculation in your own custom way.)

Note: If CallbackFunction is set to nil, then the progress information will be sent to the built-in status dialog, assuming it is currently visible. (You can show or hide the status dialog with a StatusDlg.Show or StatusDlg.Hide action.)

The callback function must be able to receive the following parameters:

CurrentFileName

(string) The filename whose size is being calculated.

PercentDone

(number) The percentage of the calculation that has been completed so far.

The callback function should return a boolean value (true or false) indicating whether the calculation should continue:

VALUE | DESCRIPTION
true | Continue with the space calculation.
false | Stop the space calculation as soon as possible.

Returns

(number) The required disk space (in bytes) needed for the install. If an error occurs, -1 will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SetupData.GetAppShortcutFolderPath

string SetupData.GetAppShortcutFolderPath (

)

Description

Gets the folder that your application's shortcuts will currently be created in. This action is useful when creating shortcuts through actions since the location and name of the target shortcut folder can change during the install.

Note: The value returned by this action is based on the %AppShortcutFolderName% session variable, and will vary subject to the install type chosen (All Users/Current User).

Parameters

None.

Returns

(string) The folder path that your application's shortcuts will currently be created in. If an error occurs, a blank string ("") will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SetupData.GetFileList

table SetupData.GetFileList (

number ListToGet = ARCHIVE_LIST )

Description

Returns a numerically indexed table containing information about each file in the setup.

Note: Some returned values are not calculated until the files have actually been installed.

Parameters

ListToGet

(number) The file list to retrieve. Choose from:

CONSTANT | VALUE | DESCRIPTION
ARCHIVE_LIST | 0 | Retrieve files in the setup archive.
EXTERNAL_LIST | 1 | Retrieve external files.
BOTH_LISTS | 2 | Retrieve both archive and external files.

Returns

(table) A numerically indexed table containing the file properties for every file within the setup. Every index in this table contains a table of file properties, indexed by the following keys:

KEY | TYPE | DESCRIPTION
AccessDate | string | The files last accessed date in the form: Tuesday, July 06, 2004, 12:46:06 PM
AccessDateISO | string | The file's last accessed date in the ISO format.
CompressFile | boolean | Whether the file is compressed within the archive.
CRC | number | The file's CRC value.
CreateBackup | boolean | Whether a backup of any existing file will be created before it is overwritten.
CreationDate | string | The files creation date in the form: Tuesday, July 06, 2004, 12:46:06 PM
CreationDateISO | string | The file's creation date in the ISO format.
CustomShortcutPath | string | The full path to the location where the custom shortcut will be created.
Destination | string | Where the file will be installed to.
FailSafeCopy | boolean | Whether a fail-safe copy will be performed.
FileDescription | string | The file's design-time description. This is the value entered in the Description field of a file's properties in the Setup Factory design environment.
FileName | string | The file's filename.
FileSource | string | The full path to the original location of the file.
FileVersion | string | The file's version.
FolderMatchMode | number | The folder match mode, if the current item is a folder reference: INCLUDE_MATCHING_FILES = 0 EXCLUDE_MATCHING_FILES = 1. If the current item is a file, then 0 is returned.
FolderRecurse | boolean | Whether the folder reference will be handled recursively. If the current item is a file, false will be returned.
FontName | string | The font name to use when registering the file as a font.
FullPath | string | The full path to the file, including file name.
IconIndex | number | The index of the icon to use for the shortcut.
IconPath | string | The external icon path to use for the shortcut.
IconShowMode | number | The Icon show mode: SW_NORMAL = 1 SW_MAXIMIZE = 3 SW_MINIMIZE = 6.
InstallOrder | number | The install order of the file.
IsArchive | boolean | Whether the original file was an archive file.
IsFolderReference | boolean | Whether the current item is a folder reference.
IsHidden | boolean | Whether the original file was hidden.
IsInstalling | boolean | Whether the current item has been installed. This value is calculated at the time of the file's installation.
IsInstallingOnReboot | boolean | Whether the current item will be installed on system reboot. This value is calculated at the time of the file's installation.
IsReadOnly | boolean | Whether the original file was read only.
IsRuntimeSourceOk | boolean | Whether the runtime source of the file is valid.
IsSystem | boolean | Whether the original file was a system file.
ModifiedDate | string | The files last modified date in the form: Tuesday, July 06, 2004, 12:46:06 PM
ModifiedDateISO | string | The file's last modified date in the ISO format.
NeverRemove | boolean | Whether this file will be left behind by the uninstall.
NewAttributeArchive | boolean | Whether the Archive attribute will be applied to the file once it is installed.
NewAttributeHidden | boolean | Whether the Hidden attribute will be applied to the file once it is installed.
NewAttributeReadOnly | boolean | Whether the Read Only attribute will be applied to the file once it is installed.
NewAttributeSystem | boolean | Whether the System attribute will be applied to the file once it is installed.
Notes | string | The notes associated with the file.
Overwrite | number | What will happen if the file already exists on the user's system: FILE_INSTALL_SAMEOLDER = 0 FILE_INSTALL_OLDER = 1 FILE_INSTALL_ALWAYS = 2 FILE_INSTALL_NEVER = 3 FILE_INSTALL_ASK = 4"
Packages | table | A numerically indexed table of all of the packages that the current item belongs to. If it does not belong to any package, nil is returned.
ProductVersion | string | The file's product version.
RegisterAsOCX | boolean | Whether the file will be registered as an OCX.
RegisterAsTLB | boolean | Whether the file will be registered as a Type Library.
RegisterAsTTF | boolean | Whether the file will be registered as a True Type Font.
SharedSystemFile | boolean | Whether the current item is a shared system file.
ShorcutInStartMenuAppFolder | boolean | Whether a shortcut be created in Start Menu > %AppFolder%
ShortcutArguments | string | The command line arguments that will be passed to the file when the user launches the shortcut.
ShortcutDescription | string | The description that will accompany the shortcut.
ShortcutInCustom | boolean | Whether a shortcut be created in the custom shortcut path
ShortcutInDesktop | boolean | Whether a shortcut be created on the desktop
ShortcutInQuickLaunch | boolean | Whether a shortcut be created in the quick launch folder
ShortcutInStartMenu | boolean | Whether a shortcut be created in the start menu
ShortcutInStartMenuPrograms | boolean | Whether a shortcut be created in Start Menu > Programs
ShortcutInStartup | boolean | Whether a shortcut be created in the Startup folder
SupressCRCCheck | boolean | Whether the CRC check is suppressed.
SupressInUseNotice | boolean | Whether the "In Use" message will be suppressed when the file is installed.
UseExternalIcon | boolean | Whether an external icon is used for the shortcut.
UseOriginalAttributes | boolean | Whether the original attributes will be used, or if the new attributes are going to be used.

If this action fails, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SetupData.GetLocalizedString

string SetupData.GetLocalizedString (

string StringID )

Description

Gets the localized text (based on current setup language) of the global (opposed to per-screen) strings.

Note: These are the strings defined in ...\Setup Factory 9\Languages\English.xml, etc.

Parameters

StringID

(string) The string ID whose localized text you want.

Returns

(string) The localized text of the given String ID. If an error occurs, a blank string ("") will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SetupData.GetPackageList

table SetupData.GetPackageList (

)

Description

Returns a numerically indexed table of the package IDs contained within the current setup.

Tip: If using the Select Packages screen, there are also DlgSelectPackages actions to manipulate the properties of the categories containing the packages.

Parameters

None.

Returns

(table) A numerically indexed table of package ids contained within the current setup. If there are no packages in the install, nil is returned.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SetupData.GetPackageProperties

table SetupData.GetPackageProperties (

string PackageName )

Description

Returns a table containing the properties of a given package.

Tip: If using the Select Packages screen, there are also DlgSelectPackages actions to manipulate the properties of the categories containing the packages.

Parameters

PackageName

(string) The name of the package whose properties you want.

Returns

(table) A table containing the properties of the given package, indexed by the following keys:

KEY | TYPE | DESCRIPTION
AdditionalDiskSpace | number | The value in KB that is added to the package size calculation. This value is defined at design time in the Additional disk space field of the package's properties dialog. You can access this table item using tb.AdditionalDiskSpace.
DisplayName | string | The current localized display name of the package according to the current setup language. You can access this table item using tb.DisplayName.
Description | string | The current localized description of the package according to the current setup language. You can access this table item using tb.Description.
Install | boolean | Whether or not the package is currently set to be installed. If true is returned, the package is currently set to be installed. A false value means it is currently not set to be installed. You can access this table item using tb.Install.
Enabled | boolean | Whether or not the current package will be enabled if shown on the Select Packages screen. A value of true means it will be shown, and false means it will not. You can access this table item using tb.Enabled.

If this action fails, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SetupData.GetSerialListNames

table SetupData.GetSerialListNames (

)

Description

Returns a numerically indexed table containing the names of all of the serial number lists in the setup.

Tip: To create/modify the serial number lists in your installer, use the Serial Numbers dialog.

Parameters

None.

Returns

(table) Returns a numerically indexed table containing the names of all of the serial number lists in the setup. If there are no lists or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SetupData.IsValidSerialNumber

boolean SetupData.IsValidSerialNumber (

string ListName,

string SerialNumber )

Description

Checks to see if a given serial number is a valid serial number in the specified serial number list.

Parameters

ListName

(string) The name of the serial number list you want to validate the serial number in.

SerialNumber

(string) The serial number you want to validate.

Returns

(boolean) True if the given serial number is present in the specified list, or false if it is not. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


SetupData.SetLocalizedString

SetupData.SetLocalizedString (

string StringID,

string Text )

Description

Sets the text of a string ID in the current language for the setup.

Parameters

StringID

(string) The string ID whose text you want to set.

Text

(string) The text you want you want to display for the string ID.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


SetupData.SetPackageProperties

SetupData.SetPackageProperties (

string PackageName,

table Properties )

Description

Sets the properties of a given package.

Tip: If using the Select Packages screen, there are also DlgSelectPackages actions to manipulate the properties of the categories containing the packages.

Parameters

PackageName

(string) The name of the package whose properties you want to set.

Properties

(table) A table containing the properties you want to set, indexed by the following keys:

KEY | TYPE | DESCRIPTION
AdditionalDiskSpace | number | The value in KB that you want to add to the package size calculation. This value can also be defined at design time using the Additional disk space field of the package's properties dialog. You can set this property using tb.AdditionalDiskSpace = 590 or {AdditionalDiskSpace=590}.
DisplayName | string | The localized display name you want the package to have. You can set this property using tb.DisplayName = "New Name" or {DisplayName="New Name"}.
Description | string | The localized description you want the package to have. You can set this property using tb.Description = "New Description" or {Description="New Description"}.
Install | boolean | Set the package to be installed. If true is passed, the package will be set to be installed. If false is passed it will not. You can set this property using tb.Install = true or {Install=true}.
Enabled | boolean | Enable the package if shown on the "Select Packages" screen. If true is passed, it will be enabled. If false is passed, it will not. You can set this property using tb.Enabled = true or {Enabled=true}.

Note: Only the properties you want to change need to be set.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


SetupData.WriteToLogFile

SetupData.WriteToLogFile (

string Text,

boolean AddTimestamp = true )

Description

Writes a string of text to the install or uninstall log file.

Note: The text will be appended to the log file as-is. Line breaks (\r\n) are not automatically included.

Note: If the Create log file option in Project Settings is not set in the install, or the Create log file option in Uninstall Settings is not set in the uninstall, this action will not generate an error. Instead, it will simply have no effect.

Parameters

Text

(string) The text you want to output to the log file.

AddTimestamp

(boolean) Whether to prepend a time stamp to the Text. Choose from:

VALUE | DESCRIPTION
true | Prepend a time stamp to the text in the form [06/18/2004 13:17:48]. (Default)
false | Don't prepend a time stamp.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Shell.CreateShortcut

Shell.CreateShortcut (

string Folder,

string Description,

string Target,

string CmdLine = "",

string WorkingFolder = "",

string IconPath = "",

number IconIndex = 0,

number WindowMode = SW_SHOWNORMAL,

table HotKey = nil,

string Comment = "",

number StartPinOption = START_OPTION_DEFAULT )

Description

Creates a shortcut on the user's system.

Note: If the target drive does not exist or cannot be accessed, the shortcut path folder will be truncated to eight characters. For more information, see Microsoft article Q263324.

Parameters

Folder

(string) The path to the folder where the shortcut will be created.

Description

(string) The label that will be given to the shortcut. This is the shortcut's "name"—i.e., what the user will see.

Target

(string) The full path and name of the file or folder that the shortcut will point to.

CmdLine

(string) The command line arguments (if any) that will be passed to the file linked by the shortcut.

WorkingFolder

(string) The working directory that will be used for the file pointed to by the shortcut.

IconPath

(string) The full path to a file containing the icon you want to use. The most common types are icon files (.ico) and executables (.exe). If no icon path is specified, the icon will be taken from the target file instead.

IconIndex

(number) The zero-based index describing which icon to use in the file. For example, an icon index of 2 means it will use the third icon in the file. If there is only one icon in the file, or if you want to use the first icon found, enter 0.

WindowMode

(number) The run mode to use when it launches the file. Choose from:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | The file will launch normally.
SW_MAXIMIZE | 3 | The file will launch maximized.
SW_SHOWMINNOACTIVE | 7 | The file will launch minimized.

HotKey

(table) A table containing an optional system-wide key combination that will launch the shortcut, indexed by the following keys:

KEY | TYPE | DESCRIPTION
shift | boolean | Whether the "shift" modifier key was held down as part of the key combination. The value true means it was held down and false means it wasn't. This value can be accessed using tb.shift.
ctrl | boolean | Whether the "ctrl" modifier key was held down as part of the key combination. The value true means it was held down and false means it wasn't. This value can be accessed using tb.ctrl.
alt | boolean | Whether the "alt" modifier key was held down as part of the key combination. The value true means it was held down and false means it wasn't. This value can be accessed using tb.alt.
keycode | number | The virtual key code of the key that was pressed. This value can be accessed using tb.keycode.

Note: If you do not want to assign a hotkey for the shortcut, nil should be passed (nil is the default value).

Comment

(string) An optional string to display in the "comment" section of the shortcut.

StartPinOption

(number) This setting controls whether or not this shortcut will be pinned to the Windows 8 Start screen if it was created under the Start menu. Choose from the following options:

Note: This setting only affects shortcuts created in the Start menu on Windows 8 / Windows Server 2012 operating systems. As of Windows 8.1 and later, developers are no longer able to pin shortcuts to the user's Start Screen. This decision by Microsoft was to let the user control what they want on their Start Screen given their preference instead of the decision being forced upon them by application developers.

CONSTANT | VALUE | DESCRIPTION
START_OPTION_DEFAULT | 0 | Use the default Windows behavior for this Start menu shortcut, based on the target file's type. In general all Start menu shortcuts that point to executables will be pinned to the Windows 8 Start screen by default.
START_OPTION_NO_PIN | 1 | Don't pin the Start menu shortcut to the Windows 8 Start screen. This allows you to remove any secondary pinned shortcuts.
START_OPTION_PIN | 2 | Pin the Start menu shortcut to the Windows 8 Start screen. This option allows you to pin Start menu shortcuts that point to non-executables such as help files (however Microsoft discourages that).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Shell.DeleteShortcut

Shell.DeleteShortcut (

string Folder,

string Description )

Description

Removes a shortcut from the user's system.

Parameters

Folder

(string) The path to the folder where the shortcut is located.

Description

(string) The shortcut's description. This is the name (or label) that appears on the shortcut.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Shell.Execute

number Shell.Execute (

string Filename,

string Verb = "open",

string Arguments = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false )

Description

Performs a shell execute on a target with a given shell verb.

Parameters

Filename

(string) The file or folder path to use.

Verb

(string) The verb to use in the shell command. Choose from:

VERB | DESCRIPTION
open | Opens the file. This is the same as if you double clicked on the file in Windows.
explore | Opens the file/folder in Windows Explorer.
edit | Opens the file for editing using the associated editor.
print | Uses the associated viewer to print the file.

Note: If you set this verb to an empty string (""):
- For Windows XP and later systems, the default verb is used if available. If not, the "open" verb is used. If neither verb is available, the system uses the first verb listed in the registry.

Arguments

(string) The command line arguments to pass to the file.

WorkingFolder

(string) The working directory that will be used for the file.

Note: This sets the current directory for the operation to something other than the folder that the file is in. Normally, you can just leave it blank.

WindowMode

(number) The window mode to use. Choose from:

CONSTANT | VALUE | DESCRIPTION
SW_SHOWNORMAL | 1 | The file will launch normally.
SW_MAXIMIZE | 3 | The file will launch maximized.
SW_MINIMIZE | 6 | The file will launch minimized.
SW_HIDE | 0 | The file will launch hidden.

WaitForReturn

(boolean) Whether the application will wait until the executable has exited before continuing:

VALUE | DESCRIPTION
true | Wait.
false | Don't wait. (Default)

Returns

(number) The process return code if the WaitForReturn parameter is set to true. If WaitForReturn is set to false 0 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: If the specified process has not terminated, the termination status returned is STILL_ACTIVE. If the process has terminated, the termination status returned may be one of the following:

The exit value specified in the ExitProcess or TerminateProcess function.
The return value from the main or WinMain function of the process.
The exception value for an unhandled exception that caused the process to terminate.


Shell.GetFolder

string Shell.GetFolder (

number Type )

Description

Returns the path to a common folder on the local system, such as "My Documents" or the user's Startup folder.

Parameters

Type

(number) The folder that you want. Choose from:

CONSTANT | VALUE | DESCRIPTION
SHF_FONTS | 20 | The path to the user’s font directory (e.g. "C:\Windows\Fonts").
SHF_MYMUSIC | 13 | The path to the user's My Music folder. For example "C:\Documents and Settings\User\My Documents\My Music."
SHF_MYMUSIC_COMMON | 53 | The path to the All Users profile My Music folder, for example "C:\Documents and Settings\All Users\Documents\My Music."
SHF_MYPICTURES | 39 | The path to the user's My Pictures folder. For example "C:\Documents and Settings\username\My Documents\My Pictures."
SHF_MYPICTURES_COMMON | 54 | The path to the All User profile My Pictures folder, for example "C:\Documents and Settings\All Users\Documents\My Pictures."
SHF_MYVIDEOS | 14 | The path to the user's My Videos folder. For example "C:\Documents and Settings\username\My Documents\My Videos."
SHF_MYVIDEOS_COMMON | 55 | The path to the All User profile My Videos folder. For example "C:\Documents and Settings\All Users\Documents\My Videos."
SHF_DESKTOP | 16 | The path to the user's Desktop directory.
SHF_DESKTOP_COMMON | 25 | The path to the All Users profile Desktop folder.
SHF_STARTMENU | 11 | The path to the user's Start Menu folder.
SHF_STARTMENU_COMMON | 22 | The path to the All Users profile Start Menu folder.
SHF_STARTMENUPROGRAMS | 2 | The path to the Programs folder in the user's Start menu.
SHF_STARTMENUPROGRAMS_COMMON | 23 | The path to the Programs folder in the All User profile Start menu.
SHF_STARTUP | 7 | The path to the user's Startup folder.
SHF_STARTUP_COMMON | 24 | The path to the All Users profile Startup folder.
SHF_COMMONFILES | 43 | The path to the user's Common Files folder. Typically, this is something like C:\Program Files\Common Files.
SHF_PROGRAMFILES | 38 | The user's Program Files folder. Typically, this is something like C:\Program Files.
SHF_MYDOCUMENTS | 5 | The path to the user's personal ("My Documents") folder on their system. Usually this is something like "C:\Documents and Settings\YourName\My Documents" on Windows XP, and "C:\Users\YourName\Documents" on Windows Vista or later.
SHF_COMMON_DOCUMENTS | 46 | The path to the documents folder common to all users. Usually this is something like "C:\Documents and Settings\All Users\Documents."
SHF_APPLICATIONDATA | 26 | The path to the Application Data folder on the user's system. Typically, this is something like "C:\Documents and Settings\YourName\Application Data." On Windows Vista or later, this is something like "C:\Users\YourName\AppData\Roaming."
SHF_APPLICATIONDATA_LOCAL | 28 | The path to the local (nonroaming) Application Data folder on the user's system. On Windows XP, this is the path from the per-user profile. Typically, this is something like "C:\Documents and Settings\YourName\Local Settings\Application Data." On Windows Vista or later, this is something like "C:\Users\YourName\AppData\Local."
SHF_APPLICATIONDATA_COMMON | 35 | The path to the All Users profile Application Data folder on the user's system.

Returns

(string) The path to the folder on the user's system that was specified in Type. If this action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.GetAutoSize

boolean StatusDlg.GetAutoSize (

)

Description

Returns the status dialog's current auto-size setting.

Note: You can enable or disable the status dialog's resize setting using the StatusDlg.SetAutoSize action.

Parameters

None.

Returns

(boolean) True if the status dialog is set to automatically resize and false if it is not. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


StatusDlg.GetMeterPos

number StatusDlg.GetMeterPos (

)

Description

Returns the status dialog's current status meter position.

Parameters

None.

Returns

(number) The current status meter position. If the action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


StatusDlg.Hide

StatusDlg.Hide (

)

Description

Hides the built-in status dialog.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.IsCancelled

boolean StatusDlg.IsCancelled (

)

Description

Returns true if the cancel button on the built-in status dialog has been clicked, or false if it hasn't.

Parameters

None.

Returns

(boolean) True if the cancel button has been clicked, false if it hasn't or an error occurs. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


StatusDlg.SetCancelled

StatusDlg.SetCancelled (

boolean Cancelled )

Description

Sets the clicked/unclicked state of the cancel button on the built-in status dialog.

Note: This affects the value that is returned by the StatusDlg.IsCancelled action.

Parameters

Cancelled

(boolean) Whether or not the cancel button was clicked:

VALUE | DESCRIPTION
true | The button was clicked.
false | The button was not clicked. (Even if it was, just pretend that it wasn't.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetAutoSize

StatusDlg.SetAutoSize (

boolean AutoSize )

Description

Sets whether or not the built-in status dialog will automatically resize when its settings change.

Parameters

AutoSize

(boolean) Whether or not the status dialog will automatically resize when its settings change:

VALUE | DESCRIPTION
true | The status dialog will automatically resize.
false | The status dialog will not resize.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetMessage

StatusDlg.SetMessage (

string Text )

Description

Sets the main description message on the built-in status dialog.

Parameters

Text

(string) The text you want to display.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetMeterPos

StatusDlg.SetMeterPos (

number Position )

Description

Sets the status meter position on the built-in status dialog.

Parameters

Position

(number) The status meter position to set.

Note: This position must be within the range defined in the StatusDlg.SetMeterRange action. If no range is defined, a default of 0-100 is used.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetMeterRange

StatusDlg.SetMeterRange (

number Begin,

number End )

Description

Sets the range of the built-in status dialog's status meter.

Parameters

Begin

(number) The beginning of the range.

Note: This must be a value greater than, or equal to 0.

End

(number) The ending of the range.

Note: This must be a value greater than 0 and less than 65534.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetStatusText

StatusDlg.SetStatusText (

string Text )

Description

Sets the status text on the built-in status dialog. This is the text that appears right above the status meter.

Parameters

Text

(string) The status text to display.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.SetTitle

StatusDlg.SetTitle (

string Text )

Description

Sets the title bar text on the built-in status dialog.

Parameters

Text

(string) The title bar text to display.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.Show

StatusDlg.Show (

number Icon = 0,

boolean Cancelled = false )

Description

Displays the built-in status dialog.

Parameters

Icon

(number) The icon to display on the dialog:

CONSTANT | VALUE | DESCRIPTION
MB_ICONNONE | 0 | None. (Default)
MB_ICONSTOP | 16 | Stop.
MB_ICONQUESTION | 32 | Question.
MB_ICONEXCLAMATION | 48 | Exclamation.
MB_ICONINFORMATION | 64 | Information.

Cancelled

(boolean) Whether the cancel button has been pressed:

VALUE | DESCRIPTION
true | The cancel button has been pressed.
false | The cancel button has not been pressed. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.ShowCancelButton

StatusDlg.ShowCancelButton (

boolean ShowCancel = true,

string ButtonText = "Cancel" )

Description

Shows or hides the cancel button on the built-in status dialog.

Parameters

ShowCancel

(boolean) Whether to show the cancel button:

VALUE | DESCRIPTION
true | The cancel button will be displayed on the status dialog. (Default)
false | The cancel button will not be displayed on the status dialog.

ButtonText

(string) The text to display on the cancel button.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


StatusDlg.ShowProgressMeter

StatusDlg.ShowProgressMeter (

boolean Show = true )

Description

Shows or hides the progress meter on the built-in status dialog.

Parameters

Show

(boolean) Whether to show the progress meter on the built-in status dialog:

VALUE | DESCRIPTION
true | Show the progress meter. (Default)
false | Hide the progress meter.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


String.AbbreviateFilePath

string String.AbbreviateFilePath (

string FilePath,

number Characters )

Description

Returns an abbreviated file path given a maximum number of characters. If the file path exceeds the maximum number of characters, folder names will be removed from the path from the right hand side until its length is less than the specified number of characters. This removal will be replaced by "...".

Note: The filename will never be truncated, therefore if the path including the filename exceeds the maximum number of characters, the abbreviation will be as close as possible.

For example: String.AbbreviateFilePath("C:\\Program Files\\Setup Factory 9\\tips.txt",35);

Returns:
C:\Program Files\...\tips.txt

Because this path is the smallest path that does not exceed 35 characters in length.

Parameters

FilePath

(string) The file path you want to abbreviate.

Characters

(number) The maximum number of characters to use in the abbreviated path.

Returns

(string) A new file path based on the specified number of characters. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Asc

number String.Asc (

string Char )

Description

Returns the ASCII code of a character (in decimal format).

Parameters

Char

(string) The character whose ASCII code you want.

Returns

(number) The ASCII code of the specified character. If the action fails, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Char

string String.Char (

number ASCII )

Description

Returns the character value of a specific ASCII code (in decimal format).

Parameters

ASCII

(number) The ASCII code of the character you want.

Returns

(string) The character value of the given ASCII code. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Compare

number String.Compare (

string Text,

string CompareTo )

Description

Performs a case-sensitive comparison between two strings.

Parameters

Text

(string) The string you want to compare to CompareTo.

CompareTo

(string) The string you want to compare to Text.

Returns

(number) A number representing the result of the comparison:

VALUE | DESCRIPTION
-1 | The string in Text is less than (<) the string in CompareTo.
0 | The string in Text is equal to (=) the string in CompareTo.
1 | The string in Text is greater than (>) the string in CompareTo.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.CompareFileVersions

number String.CompareFileVersions (

string Version,

string CompareTo )

Description

Compares two file version strings.

Parameters

Version

(string) The first file version string you want to compare.

CompareTo

(string) The second file version string you want to compare.

Returns

(number) A number representing the result of the comparison:

VALUE | DESCRIPTION
-1 | The string in Version is less than (<) the string in CompareTo.
0 | The string in Version is equal to (=) the string in CompareTo.
1 | The string in Version is greater than (>) the string in CompareTo.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.CompareNoCase

number String.CompareNoCase (

string Text,

string CompareTo )

Description

Performs a case-insensitive comparison between two strings.

Parameters

Text

(string) The string you want to compare to CompareTo.

CompareTo

(string) The string you want to compare to Text.

Returns

(number) A number representing the result of the comparison:

VALUE | DESCRIPTION
-1 | The string in Text is less than (<) the string in CompareTo.
0 | The string in Text is equal to (=) the string in CompareTo.
1 | The string in Text is greater than (>) the string in CompareTo.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Concat

string String.Concat (

string StartString,

string EndString )

Description

Adds (or "concatenates") two strings together and returns the result as a new string.

Note: This does not modify either of the source strings.

Parameters

StartString

(string) The string to be added to. This string will be appear at the start of the new string.

EndString

(string) The string to add (append) to the StartString. This string will appear after the StartString.

Returns

(string) The new concatenated string beginning with the StartString and ending with the EndString.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Find

number String.Find (

string SearchString,

string Pattern,

number StartAt = 1,

boolean CaseSensitive = false )

Description

Finds the first occurrence of a sub-string within a string.

Parameters

SearchString

(string) The string to be searched.

Pattern

(string) The sub-string to search for.

StartAt

(number) The position in the SearchString where the search will begin. The default is 1, which is the first character in the string.

CaseSensitive

(boolean) Whether the search will be case sensitive:

VALUE | DESCRIPTION
true | Perform a case-sensitive search.
false | Ignore the character case in the search. (Default)

Returns

(number) The first position in the string where the sub-string was found. If the sub-string cannot be found or an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.GetFormattedSize

string String.GetFormattedSize (

number SizeInBytes,

number Format = FMTSIZE_AUTOMATIC,

boolean ShowCommas = true )

Description

Given a number of bytes, returns a formatted string that converts to bytes, KB, MB or GB and optionally inserts commas.

Parameters

SizeInBytes

(number) The number of raw bytes to convert.

Format

(number) The format to return. The following constants are defined:

CONSTANT | VALUE | DESCRIPTION
FMTSIZE_AUTOMATIC | 1 | Automatically choose the best format based on the size.
FMTSIZE_BYTES | 2 | Format the value in bytes.
FMTSIZE_KB | 3 | Format the value in Kilobytes.
FMTSIZE_MB | 4 | Format the value in Megabytes.
FMTSIZE_GB | 5 | Format the value in Gigabytes.

ShowCommas

(boolean) Whether to insert commas into the result (i.e. "63636" becomes "63,636").

Returns

(string) A formatted string given a number of bytes. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Left

string String.Left (

string LeftString,

number NumChar )

Description

Creates a new string from the left-most x characters of an existing string.

Parameters

LeftString

(string) The string to copy the characters from.

NumChar

(number) The number of characters to copy from the left hand side of the string.

Returns

(string) A string consisting of the specified number of characters from the beginning of the string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Length

number String.Length (

string LengthString )

Description

Returns the number of characters in a string.

Parameters

LengthString

(string) The string whose length you want.

Returns

(number) The number of characters in the specified string. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Lower

string String.Lower (

string ToLower )

Description

Returns an all lowercase version of a string.

Note: The original string will not be modified.

Parameters

ToLower

(string) The string to convert to lowercase.

Returns

(string) The all lowercase version of the specified string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.MakePath

string String.MakePath (

table PathParts )

Description

Returns a path based upon the elements in a specified table.

Parameters

PathParts

(table) A table containing each part of the path. The table should be indexed as follows:

KEY | TYPE | VALUE
Drive | string | The drive portion of the path (drive letter followed by a colon, for example, C:).
Folder | string | All of the folders within the path. This must begin with a backslash (for example, \MyFolder1\MyFolder2\).
Filename | string | The filename in the path (for example, "myfile").
Extension | string | The file extension in the path (for example, ".exe").

Returns

(string) A path string composed of the specified table elements. If for some reason, the path cannot be created or an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Note: The path created cannot exceed the Windows maximum path of 260 characters.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Mid

string String.Mid (

string MidString,

number CharStart,

number NumChar )

Description

Returns a specified range of characters from a string.

Parameters

MidString

(string) The string to copy the characters from.

CharStart

(number) The position in the string to start copying from.

NumChar

(number) The number of characters from CharStart to copy. Use -1 to get all of the characters to the end of the string.

Returns

(string) The specified range of characters from the source string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Repeat

string String.Repeat (

string RepeatString,

number NumRepeat )

Description

Repeats a string a given number of times.

Parameters

RepeatString

(string) The string to copy the characters from.

NumRepeat

(number) The number of times to repeat the string.

Returns

(string) A string containing the specified number of copies of the source string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Replace

string String.Replace (

string SearchString,

string Pattern,

string ReplaceString,

boolean CaseSensitive = false )

Description

Searches a string for a sub-string and replaces every occurrence of it with a new sub-string.

Note: The source string will not be modified.

Parameters

SearchString

(string) The string to search.

Pattern

(string) The sub-string to search for.

ReplaceString

(string) The replacement sub-string.

CaseSensitive

(boolean) Whether the search will be case sensitive:

VALUE | DESCRIPTION
true | Perform a case-sensitive search.
false | Ignore the character case in the search. (Default)

Returns

(string) A copy of the source string containing the replacement sub-string. If the sub-string is not found, a copy of the source string is returned.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.ReverseFind

number String.ReverseFind (

string SearchString,

string Pattern,

boolean CaseSensitive = false )

Description

Finds the first occurrence of a sub-string within a string by searching it from right to left.

Parameters

SearchString

(string) The string to be searched.

Pattern

(string) The sub-string to search for.

CaseSensitive

(boolean) Whether the search will be case sensitive:

VALUE | DESCRIPTION
true | Perform a case-sensitive search.
false | Ignore the character case in the search. (Default)

Returns

(number) The first position in the string where the sub-string was found, searching from right to left. If the sub-string cannot be found or an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Right

string String.Right (

string RightString,

number NumChar )

Description

Creates a new string from the right-most x characters of an existing string.

Parameters

RightString

(string) The string to copy the characters from.

NumChar

(number) The number of characters to copy from the right hand side of the string.

Returns

(string) A string consisting of the specified number of characters from the end of the string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.SplitPath

table String.SplitPath (

string Path )

Description

Splits a path up into it's drive, folders, filename, and file extension and returns a table containing each part.

Parameters

Path

(string) The path that you want to split up.

Returns

(table) A table containing each component of the path, indexed by the following keys:

KEY | TYPE | DESCRIPTION
Drive | string | The drive portion of the path (for example, C:).
Folder | string | All of the folders within the path (for example, \MyFolder1\MyFolder2\).
Filename | string | The filename in the path (for example, "myfile").
Extension | string | The file extension in the path (for example, ".exe").

Note: If any portion of the path is not available, an empty string will be returned ("") as it's value.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.ToNumber

number String.ToNumber (

string NumericString )

Description

Converts a numeric string into a numeric value.

Parameters

NumericString

(string) A string containing numeric characters. For example: "10", "3.2", "-5".

Returns

(number) The numeric value of the given numeric string. If the string does not contain numeric characters, 0 will be returned.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.TrimLeft

string String.TrimLeft (

string SourceString,

string CharactersToTrim = nil )

Description

Trims specific characters from the left hand side of a source string. Each character in CharactersToTrim will be removed from the left hand side of the SourceString until no characters match.

Note: You can also use this action to remove beginning newlines, space, and tab characters from the string by passing nil as the CharactersToTrim parameter.

Parameters

SourceString

(string) The source string you want to trim.

CharactersToTrim

(string) The string whose characters you want to trim from the source string. The default is nil which can be used to remove beginning newlines, space and tab characters.

Returns

(string) A string with the specified characters removed from the left hand side of the source string. If an error occurs, the source string is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.TrimRight

string String.TrimRight (

string SourceString,

string CharactersToTrim = nil )

Description

Trims specific characters from the right hand side of a source string. Each character in CharactersToTrim will be removed from the right hand side of the SourceString until no characters match.

Note: You can also use this action to remove trailing newlines, space, and tab characters from the string by passing nil as the CharactersToTrim parameter.

Parameters

SourceString

(string) The source string you want to trim.

CharactersToTrim

(string) The string whose characters you want to trim from the source string. The default is nil which can be used to remove trailing newlines, space and tab characters.

Returns

(string) A string with the specified characters removed from the right hand side of the source string. If an error occurs, the source string is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


String.Upper

string String.Upper (

string ToUpper )

Description

Returns an all uppercase version of a string.

Note: The original string will not be modified.

Parameters

ToUpper

(string) The string to convert to uppercase.

Returns

(string) The all uppercase version of the specified string. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.EnumerateProcesses

table System.EnumerateProcesses (

)

Description

Returns a table containing a list of all the currently running processes and the full paths to the files that spawned them.

Parameters

None.

Returns

(table) A table of process IDs and the paths to the files that spawned them. In this table the process IDs are the keys, and the values are the paths to the executables that spawned the processes. If an error occurs, or there were no processes (there should always be processes) nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


System.GetDate

string System.GetDate (

number DateType )

Description

Gets the current date in a variety of formats.

Parameters

DateType

(number) Return the date in the format:

CONSTANT | VALUE | DESCRIPTION
DATE_FMT_US | 0 | North American (MM/DD/YYYY)
DATE_FMT_EUROPE | 1 | European (DD/MM/YYYY)
DATE_FMT_ISO | 2 | ISO Date (YYYY-MM-DD)
DATE_FMT_JULIAN | 3 | Julian Date (an integer value representing the number of days since midnight on January 1, 4713 B.C.)
DATE_FMT_MONTH | 4 | Month (MM)
DATE_FMT_DAY | 5 | Day (DD)
DATE_FMT_YEAR | 6 | Year (YYYY)
DATE_FMT_DAYOFWEEK | 7 | Day of the week (1-7)

Returns

(string) The date in the format specified by DateType. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetDefaultLangID

table System.GetDefaultLangID (

)

Description

Returns a table containing the primary and secondary language ID code for the language on the local system.

Parameters

None.

Returns

(table) A table containing the primary and secondary language ID code, indexed by "Primary" and "Secondary." If the language information cannot be determined or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetDisplayInfo

table System.GetDisplayInfo (

)

Description

Returns a table containing the display information of the user's system.

Parameters

None.

Returns

(table) A table containing the user's display information, indexed by the following keys:

KEY | TYPE | DESCRIPTION
Width | number | The user's screen width in pixels (for example 800).
Height | number | The user's screen height in pixels (for example 600).
ColorDepth | number | The color depth of the user's video display, in bits per pixel. For example, 8 for 256 Colors, 16 for High Color or 32 for True Color.

If this information cannot be determined, or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetLANInfo

table System.GetLANInfo (

)

Description

Returns a table containing the user's LAN information.

Parameters

None.

Returns

(table) A table containing the user's LAN information indexed by the following categories:

KEY | TYPE | DESCRIPTION
Host | string | The user's local computer name. If the user's system is not connected to a LAN, this value will default to "Unknown" on non-NT systems. NT-based systems always return a host value.
Domain | string | The network domain that the user is logged in to. If the user's system is not connected to a LAN, this value will default to "Unknown " on non-NT systems. NT-based systems always return a domain value.
User | string | The user name that the user is currently logged in as. If the user's system is not connected to a LAN, this value will default to "Unknown."
IP | string | The user's IP address on the local network. If the user's system is not connected to a LAN, this value will default to "Unknown."
NIC | string | The MAC address of the user's NIC (network interface card). If the user's system does not contain a network card, this value will default to "Unknown."

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetMemoryInfo

table System.GetMemoryInfo (

)

Description

Returns a table containing the system's memory information.

Parameters

None.

Returns

(table) A table containing the system's memory information indexed by the following categories. If the system's memory information could not be accessed, nil is returned.

KEY

TYPE

DESCRIPTION

AvailablePageFile

number

The number of MB available in the paging file. You can access this value using tablename.AvailablePageFile.

AvailableRAM

number

The number of MB of physical memory available. You can access this value using tablename.AvailableRAM.

AvailableVirtual

number

The number of MB of unreserved and uncommitted memory in the user mode portion of the virtual address space of the calling process. You can access this value using tablename.AvailableVirtual.

MemoryLoad

number

A number between 0 and 100 that gives a general idea of current memory utilization, in which 0 indicates no memory use and 100 indicates full memory use. You can access this value using tablename.MemoryLoad.

TotalPageFile

number

The total number of MB that can be stored in the paging file. Note that this number does not represent the actual physical size of the paging file on disk. You can access this value using tablename.TotalPageFile.

TotalRAM

number

The total number of MB of physical memory available to Windows. You can access this value using tablename.TotalRAM.

Note: This value may or may not be the "actual" amount of RAM you have on your system. Usually the value returned will be 2 or 3 MB less than the actual RAM value. Keep this in mind if you are using this option for system requirements.

TotalVirtual

number

The total number of MB that can be described in the user mode portion of the virtual address space of the calling process. You can access this value using tablename.TotalVirtual.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetOSName

string System.GetOSName (

)

Description

Gets the name of the operating system the user is running:

Windows 10

Windows Server 10

Windows 8.1

Windows Server 2012 R2

Windows 8

Windows Server 2012

Windows 7

Windows Server 2008 R2

Windows Vista

Windows Server 2008

Windows XP

Windows Server 2003

Parameters

None.

Returns

(string) A string containing the name of the OS the user is running on their system. If this action fails, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetOSProductInfo

number System.GetOSProductInfo (

)

Description

Gets the product type for the operating system. Only supported on Windows Vista, Windows Server 2008, or later.

Parameters

None.

Returns

(number) Returns a numeric value representing the product type for the operating system. If the action is not supported, -1 will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

CONSTANT | VALUE | DESCRIPTION
PRODUCT_UNDEFINED | 0 | An unknown product
PRODUCT_ULTIMATE | 1 | Ultimate
PRODUCT_HOME_BASIC | 2 | Home Basic
PRODUCT_HOME_PREMIUM | 3 | Home Premium
PRODUCT_ENTERPRISE | 4 | Enterprise
PRODUCT_HOME_BASIC_N | 5 | Home Basic N
PRODUCT_BUSINESS | 6 | Business
PRODUCT_STANDARD_SERVER | 7 | Server Standard
PRODUCT_DATACENTER_SERVER | 8 | Server Datacenter (full installation)
PRODUCT_SMALLBUSINESS_SERVER | 9 | Windows Small Business Server
PRODUCT_ENTERPRISE_SERVER | 10 | Server Enterprise (full installation)
PRODUCT_STARTER | 11 | Starter
PRODUCT_DATACENTER_SERVER_CORE | 12 | Server Datacenter (core installation)
PRODUCT_STANDARD_SERVER_CORE | 13 | Server Standard (core installation)
PRODUCT_ENTERPRISE_SERVER_CORE | 14 | Server Enterprise (core installation)
PRODUCT_ENTERPRISE_SERVER_IA64 | 15 | Server Enterprise for Itanium-based Systems
PRODUCT_BUSINESS_N | 16 | Business N
PRODUCT_WEB_SERVER | 17 | Web Server (full installation)
PRODUCT_CLUSTER_SERVER | 18 | HPC Edition
PRODUCT_HOME_SERVER | 19 | Windows Storage Server 2008 R2 Essentials
PRODUCT_STORAGE_EXPRESS_SERVER | 20 | Storage Server Express
PRODUCT_STORAGE_STANDARD_SERVER | 21 | Storage Server Standard
PRODUCT_STORAGE_WORKGROUP_SERVER | 22 | Storage Server Workgroup
PRODUCT_STORAGE_ENTERPRISE_SERVER | 23 | Storage Server Enterprise
PRODUCT_SERVER_FOR_SMALLBUSINESS | 24 | Windows Server 2008 for Windows Essential Server Solutions
PRODUCT_SMALLBUSINESS_SERVER_PREMIUM | 25 | Small Business Server Premium
PRODUCT_HOME_PREMIUM_N | 26 | Home Premium N
PRODUCT_ENTERPRISE_N | 27 | Enterprise N
PRODUCT_ULTIMATE_N | 28 | Ultimate N
PRODUCT_WEB_SERVER_CORE | 29 | Web Server (core installation)
PRODUCT_MEDIUMBUSINESS_SERVER_MANAGEMENT | 30 | Windows Essential Business Server Management Server
PRODUCT_MEDIUMBUSINESS_SERVER_SECURITY | 31 | Windows Essential Business Server Security Server
PRODUCT_MEDIUMBUSINESS_SERVER_MESSAGING | 32 | Windows Essential Business Server Messaging Server
PRODUCT_SERVER_FOUNDATION | 33 | Server Foundation
PRODUCT_HOME_PREMIUM_SERVER | 34 | Windows Home Server 2011
PRODUCT_SERVER_FOR_SMALLBUSINESS_V | 35 | Windows Server 2008 without Hyper-V for Windows Essential Server Solutions
PRODUCT_STANDARD_SERVER_V | 36 | Server Standard without Hyper-V
PRODUCT_DATACENTER_SERVER_V | 37 | Server Datacenter without Hyper-V (full installation)
PRODUCT_ENTERPRISE_SERVER_V | 38 | Server Enterprise without Hyper-V (full installation)
PRODUCT_DATACENTER_SERVER_CORE_V | 39 | Server Datacenter without Hyper-V (core installation)
PRODUCT_STANDARD_SERVER_CORE_V | 40 | Server Standard without Hyper-V (core installation)
PRODUCT_ENTERPRISE_SERVER_CORE_V | 41 | Server Enterprise without Hyper-V (core installation)
PRODUCT_HYPERV | 42 | Microsoft Hyper-V Server
PRODUCT_STORAGE_EXPRESS_SERVER_CORE | 43 | Storage Server Express (core installation)
PRODUCT_STORAGE_STANDARD_SERVER_CORE | 44 | Storage Server Standard (core installation)
PRODUCT_STORAGE_WORKGROUP_SERVER_CORE | 45 | Storage Server Workgroup (core installation)
PRODUCT_STORAGE_ENTERPRISE_SERVER_CORE | 46 | Storage Server Enterprise (core installation)
PRODUCT_STARTER_N | 47 | Starter N
PRODUCT_PROFESSIONAL | 48 | Professional
PRODUCT_PROFESSIONAL_N | 49 | Professional N
PRODUCT_SB_SOLUTION_SERVER | 50 | Windows Small Business Server 2011 Essentials
PRODUCT_SERVER_FOR_SB_SOLUTIONS | 51 | Server For SB Solutions
PRODUCT_STANDARD_SERVER_SOLUTIONS | 52 | Server Solutions Premium
PRODUCT_STANDARD_SERVER_SOLUTIONS_CORE | 53 | Server Solutions Premium (core installation)
PRODUCT_SB_SOLUTION_SERVER_EM | 54 | Server For SB Solutions EM
PRODUCT_SERVER_FOR_SB_SOLUTIONS_EM | 55 | Server For SB Solutions EM
PRODUCT_SOLUTION_EMBEDDEDSERVER | 56 | Windows MultiPoint Server
PRODUCT_SOLUTION_EMBEDDEDSERVER_CORE | 57 |
PRODUCT_ESSENTIALBUSINESS_SERVER_MGMT | 59 | Windows Essential Server Solution Management
PRODUCT_ESSENTIALBUSINESS_SERVER_ADDL | 60 | Windows Essential Server Solution Additional
PRODUCT_ESSENTIALBUSINESS_SERVER_MGMTSVC | 61 | Windows Essential Server Solution Management SVC
PRODUCT_ESSENTIALBUSINESS_SERVER_ADDLSVC | 62 | Windows Essential Server Solution Additional SVC
PRODUCT_SMALLBUSINESS_SERVER_PREMIUM_CORE | 63 | Small Business Server Premium (core installation)
PRODUCT_CLUSTER_SERVER_V | 64 | Server Hyper Core V
PRODUCT_EMBEDDED | 65 |
PRODUCT_STARTER_E | 66 | Not supported
PRODUCT_HOME_BASIC_E | 67 | Not supported
PRODUCT_HOME_PREMIUM_E | 68 | Not supported
PRODUCT_PROFESSIONAL_E | 69 | Not supported
PRODUCT_ENTERPRISE_E | 70 | Not supported
PRODUCT_ULTIMATE_E | 71 | Not supported
PRODUCT_ENTERPRISE_EVALUATION | 72 | Server Enterprise (evaluation installation)
PRODUCT_MULTIPOINT_STANDARD_SERVER | 76 | Windows MultiPoint Server Standard (full installation)
PRODUCT_MULTIPOINT_PREMIUM_SERVER | 77 | Windows MultiPoint Server Premium (full installation)
PRODUCT_STANDARD_EVALUATION_SERVER | 79 | Server Standard (evaluation installation)
PRODUCT_DATACENTER_EVALUATION_SERVER | 80 | Server Datacenter (evaluation installation)
PRODUCT_ENTERPRISE_N_EVALUATION | 84 | Enterprise N (evaluation installation)
PRODUCT_STORAGE_WORKGROUP_EVALUATION_SERVER | 95 | Storage Server Workgroup (evaluation installation)
PRODUCT_STORAGE_STANDARD_EVALUATION_SERVER | 96 | Storage Server Standard (evaluation installation)
PRODUCT_CORE_N | 98 | Windows 8 N
PRODUCT_CORE_COUNTRYSPECIFIC | 99 | Windows 8 China
PRODUCT_CORE_SINGLELANGUAGE | 100 | Windows 8 Single Language
PRODUCT_CORE | 101 | Windows 8
PRODUCT_PROFESSIONAL_WMC | 103 | Professional with Media Center
PRODUCT_UNLICENSED | 2882382797 | The product has not been activated and is no longer in the grace period.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetOSVersionInfo

table System.GetOSVersionInfo (

)

Description

Returns a table containing the version information of the operating system the user is running.

Parameters

None.

Returns

(table) A table containing the OS version information indexed by version categories.

KEY | TYPE | DESCRIPTION
MajorVersion | string | The major version number of the OS. If the version was 5.00.2195, "5" would be returned.
MinorVersion | string | The minor version number of the OS. If the version was 5.00.2195, "0" would be returned.
BuildNumber | string | The build number of the OS version. If the version was 5.00.2195, "2195" would be returned.
PlatformId | string | Returns "1" if the OS is non-NT based and "2" if the OS is NT based (XP, Vista, Server "Longhorn", Windows Server 2008, Windows 7, Windows Server 2008 R2, Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10, Windows Server 10).
CSDVersion | string | The name of the most recently installed service pack for the OS, such as "Service Pack 3."

Additional table values are available for the following client and server operating systems:
Client: Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Vista, Windows XP, and later.
Server: Windows Server 10, Windows Server 2012 R2, Windows Server 2012, Requires Windows Server 2008 R2, Windows Server 2008, Windows Server "Longhorn", Windows Server 2003, and later.

Note: If the target operating system is not one of the above mentioned client or server operating systems, -1 will be returned for keys of type number and false for keys of type boolean.

KEY | TYPE | DESCRIPTION
ServicePackMajor | number | The major version number of the latest Service Pack installed on the system. For example, for Service Pack 3, the major version number is 3. If no Service Pack has been installed, the value is zero.
ServicePackMinor | number | The minor version number of the latest Service Pack installed on the system. For example, for Service Pack 3, the minor version number is 0.
ProductType | number | One of the numeric values "1", "2" or "3" will be returned. These values are defined as follows: 1 - The system is running Windows 10, Windows 8.1, Windows 8, Windows 7, Windows Vista, Windows XP Professional, or Windows XP Home Edition. 2 - The system is a domain controller. 3 - The system is a server.
BackOffice | boolean | Whether or not Microsoft BackOffice components are installed. If they are installed the value true is returned. If they are not installed, false is returned.
Blade | boolean | Whether or not Windows Server 2003, Web Edition is installed. If it is installed the value true is returned. If it is not installed, false is returned.
ComputeServer | boolean | Whether Windows Server 2003, Compute Cluster Edition is installed.
DataCenter | boolean | Whether or not Windows Server 2008 Datacenter, or Windows Server 2003 Datacenter Edition is installed. If one of them is installed, the value true is returned. If none are installed, false is returned.
Enterprise | boolean | Whether or not Windows Server Enterprise, Windows Server 2003, Enterprise Edition, Windows Server 2008 Enterprise is installed. If one of them is installed, the value true is returned. If none are installed, false is returned.
EmbeddedNT | boolean | Whether or not Windows XP Embedded is installed.
Personal | boolean | Whether or not Windows Vista Home Premium, Windows Vista Home Basic, or Windows XP Home Edition is installed. If it is installed, the value true is returned. If it is not installed, false is returned.
SingleUserTerminalService | boolean | Whether or not Terminal Services is installed, but only one interactive session is supported. If only one interactive session is supported, the value true is returned. If Terminal Services is not installed, or supports more than one interactive session, false is returned.
SmallBusiness | boolean | Whether or not Microsoft Small Business Server was once installed on the system, but may have been upgraded to another version of Windows. If it was installed at some point, the value true is returned. If it was never installed, false is returned.
SmallBusinessRestricted | boolean | Whether or not Microsoft Small Business Server is installed with the restrictive client license in force. If it is installed with the restrictive client license in force, the value true is returned. If it is not, false is returned.
Terminal | boolean | Whether or not Terminal Services is installed. If it is installed, the value true is returned. If it is not installed, false is returned.
Communications | boolean | Whether or not Communication components installed. If they are installed, the value true is returned. If they are not installed, false is returned.
Server2003R2 | boolean | Whether or not the operating system is Windows Storage Server 2003 R2 or Windows Storage Server 2003 is installed. If it is, true is returned. If it is not, false is returned.
XPMediaCenterEdition | boolean | Whether or not the operating system is Windows XP Media Center Edition. If it is, true is returned. If it is not, false is returned.
StarterEdition | boolean | Whether or not the operating system is Windows 7 Starter Edition, Windows Vista Starter, or Windows XP Starter Edition. If it is, true is returned. If it is not, false is returned.
TabletPCEdition | boolean | Returns true if the current operating system is the Windows XP Tablet PC edition or if the current operating system is Windows Vista, Windows 7 and the Tablet PC Input service is started. Otherwise returns false.

If this action fails, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetTime

string System.GetTime (

number TimeType )

Description

Gets the current time in a variety of formats.

Parameters

TimeType

(number) Return the time in the format:

CONSTANT | VALUE | DESCRIPTION
TIME_FMT_MIL | 0 | Military Time (HH:MM:SS)
TIME_FMT_AMPM | 1 | AM/PM Time (HH:MM:SS AM/PM)
TIME_FMT_SEC | 2 | Seconds (SS)
TIME_FMT_MIN | 3 | Minutes (MM)
TIME_FMT_HOUR | 4 | Hours (HH)

Returns

(string) The time in the format specified by TimeType. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetUserInfo

table System.GetUserInfo (

)

Description

Returns a table containing the current user's information.

Parameters

None.

Returns

(table) A table containing the current user's information, indexed by the following keys:

KEY

TYPE

DESCRIPTION

RegOwner

string

The registered owner of the system. If this information cannot be determined, an empty string will be returned.

RegOrganization

string

The organization of the registered owner of the system. If this information cannot be determined, an empty string will be returned.

IsAdmin

boolean

Whether the current user is logged into Windows XP/Vista or later with administrator permissions. True will be returned if the user has administrator permissions and false if they do not. If this information cannot be determined, false will be returned.

Note: On Windows Vista or later, with UAC enabled, administrators are logged in with standard user privileges with the ability to elevate. This will determine if the user has already been elevated to the full access token. See Installing on Windows Vista or Later for more information.

IsVistaAdminLimitedToken

boolean

Returns True if the current user on Windows Vista or later (only) is part of the administrator's group, but only contains a standard user access token (has not been elevated to full administrator privileges). False is returned if UAC (User Account Control) is off, or if the user has already been elevated. For all non-Vista operating systems, the result will be the same as the normal administrator check IsAdmin as mentioned above.

Note: See Installing on Windows Vista or Later for more information.

If this action fails, nil will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.GetUserSID

string System.GetUserSID (

string UserName )

Description

Gets the string SID value for a user on the local computer.

Tip: This action is normally used to get the SID value for use in the File.SetPermissions action.

Parameters

UserName

(string) The username of the user to get the SID value for.

Returns

(string) Returns the SID value or a blank string if this action failed. If this action fails you can reference the System.UserSIDError variable to get the system error code for this action. For more information on the possible system error codes and their meanings, see http://msdn.microsoft.com/en-us/library/ms681381%28v=VS.85%29.aspx

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.Is64BitOS

boolean System.Is64BitOS (

)

Description

Determines if the user is running a 64 bit operating system (OS).

Parameters

None.

Returns

(boolean) True if the user's OS is 64 bit, false if it is not.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


System.IsSystemRestoreAvailable

boolean System.IsSystemRestoreAvailable (

)

Description

Determines whether or not the system restore service is available on the current system.

Note: The system restore service can only be accessed on Windows XP or later.

System Restore does not restore user data or documents, so it will not cause users to lose their files, e-mail, browsing history, or favorites. Only certain file types are monitored by system restore. See the System Restore Monitored File Extensions topic for details. System Restore also saves a full snapshot of the registry.

Parameters

None.

Returns

(boolean) True if the system restore service is available on the current system, or false if not. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.Reboot

System.Reboot (

)

Description

Reboots the user's system.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.RegisterActiveX

System.RegisterActiveX (

string Filename )

Description

Registers an ActiveX control on the local system.

Note: This will only work for controls that properly support the DLLRegisterServer interface.

Parameters

Filename

(string) The full path to the ActiveX control file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.RegisterFont

System.RegisterFont (

string Filename,

string Fontname,

boolean Permanent = true )

Description

Registers a TrueType font (.ttf file) on the local system.

Parameters

Filename

(string) The full path to the font file. The file must be a valid Windows .TTF file.

Fontname

(string) The name you want to use for the TrueType font (as it will appear in the Registry).

Permanent

(boolean) Whether to permanently register the font file:

VALUE | DESCRIPTION
true | The font file will be permanently registered on the user's system. (Default)
false | The font file will be temporarily registered on the user's system. This means it will be registered until a system reboot.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.RegisterTypeLib

System.RegisterTypeLib (

string Filename )

Description

Registers a type library file (.tlb) on the local system.

Parameters

Filename

(string) The full path to the TypeLib file (.tlb).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.RemoveRestorePoint

System.RemoveRestorePoint (

number SequenceNum )

Description

Removes a system restore point given the sequence number generated by the System.SetRestorePoint action.

Note: This system restore action is only supported on Windows XP or later and may require administrative privileges.

Parameters

SequenceNum

(number) The sequence number of the restore point you want to remove. This is the value generated by the System.SetRestorePoint action.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.SetRestorePoint

number System.SetRestorePoint (

number EventType,

number RestorePointType,

number SequenceNum,

string Description )

Description

Creates a system restore point on the computer and returns the sequence number that was used.

To create a proper restore point, this action needs to be called twice. The first time, EventType should be set to SYSTEM_CHANGE_BEGIN. The second time, EventType should be set to SYSTEM_CHANGE_END.

Note: This system restore action is only supported on Windows XP or later and may require administrative privileges. You can use the System.IsSystemRestoreAvailable action to determine whether or not the system restore service is available.

System Restore does not restore user data or documents, so it will not cause users to lose their files, e-mail, browsing history, or favorites. Only certain file types are monitored by system restore. See the System Restore Monitored File Extensions topic for details. System Restore also saves a full snapshot of the registry.

Parameters

EventType

(number) The type of event for system restore. Choose from:

CONSTANT | VALUE | DESCRIPTION
SYSTEM_CHANGE_BEGIN | 100 | Notify that a system change has begun.
SYSTEM_CHANGE_END | 101 | Notify that a system change has ended.

RestorePointType

(number) The type of restore point to set. Choose from:

CONSTANT | VALUE | DESCRIPTION
SYS_RESTORE_APP_INSTALL | 0 | The restore point wraps an application install.
SYS_RESTORE_APP_UNINSTALL | 1 | The restore point wraps an application uninstall.
SYS_RESTORE_APP_DDRIVER_INSTALL | 10 | The restore point wraps a device driver install.
SYS_RESTORE_MODIFY_SETTINGS | 12 | The restore point wraps the modifications of an application's settings. (Only System Restore monitored file extensions are restored)
SYS_RESTORE_CANCELLED_OPERATION | 13 | The operation that the restore point was set to wrap has been canceled. As a result the restore point needs to be deleted. For example, an install would use this flag when a user cancels the installation. Note: You can delete a restore point using the System.RemoveRestorePoint action.

SequenceNum

(number) The sequence number of the restore point. When calling this action with the EventType set to SYSTEM_CHANGE_BEGIN, pass 0 as this parameter. This will cause the action to return the sequence number of the restore point that has been created. Use that sequence number in all subsequent calls to any restore point actions.

Description

(string) The description of the restore point that will show in Microsoft's System Restore utility. A maximum of 64 characters can be used.

Returns

(number) Returns the sequence number that was used to create the system restore point. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


System.TerminateProcess

boolean System.TerminateProcess (

number ProcessID )

Description

Terminates a process given its process ID. Process IDs can be retrieved using the System.EnumerateProcesses action.

Parameters

ProcessID

(number) The integer value that represents the specific process on the user's system. Process IDs can be retrieved using the System.EnumerateProcesses action.

Returns

(boolean) True if the process was terminated successfully, or false if it failed. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


System.UnregisterActiveX

System.UnregisterActiveX (

string Filename )

Description

Unregisters an ActiveX control on the local system.

Note: This will only work for controls that properly support the DLLUnregisterServer interface.

Parameters

Filename

(string) The full path to the ActiveX control file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


System.UnregisterFont

System.UnregisterFont (

string Filename,

string Fontname,

boolean Permanent = true )

Description

Unregisters a TrueType font (.ttf file) on the local system. This removes the font's registration with the system font table.

Parameters

Filename

(string) The full path to the font file. The file must be a valid Windows .TTF file.

Fontname

(string) The name of the TrueType font (as it appears in the Registry).

Permanent

(boolean) Whether to permanently unregister the font file:

VALUE | DESCRIPTION
true | The font file will be permanently unregistered on the user's system. (Default)
false | The font file will be temporarily unregistered on the user's system. This means it will be unregistered until a system reboot.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Table.Concat

string Table.Concat (

table SourceTable,

string Separator,

number Start = 1,

number End = TABLE_ALL )

Description

Returns a string containing some or all of the values in a table. The values will be separated by the delimiter of your choice.

Parameters

SourceTable

(table) The table whose values you want to concatenate.

Separator

(string) The delimiter to use to separate the table values.

Start

(number) The index of the first item in the table that you want to concatenate. The default for this parameter is 1.

End

(number) The index of the last item in the table that you want to concatenate. The constant TABLE_ALL or -1 can be used to specify the last index in the table. TABLE_ALL is useful when you want to concatenate the entire table contents.

Returns

(string) A string containing the table values, separated by the delimiter you chose. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Table.Count

number Table.Count (

table SourceTable )

Description

Returns the total number of items in a table.

Parameters

SourceTable

(table) The table whose number of items you want.

Returns

(number) The total number of items in the table. If the table is empty, 0 is returned.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Table.Insert

Table.Insert (

table SourceTable,

number Position,

variant Value )

Description

Inserts an item into a numerically indexed table at a specific position.

Parameters

SourceTable

(table) The table to insert the item into.

Position

(number) The index in the table where you want to insert the item.

Value

(variant) The item you want to insert into the table.

Returns

Nothing.


Table.Remove

variant Table.Remove (

table SourceTable,

number Position )

Description

Removes a specific item from a numerically indexed table and returns it's value.

Parameters

SourceTable

(table) The table you want to remove an item from.

Position

(number) The table index of the item to remove from the table.

Returns

(variant) The value of the item that was removed from the table.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Table.Sort

Table.Sort (

table SourceTable,

function Compare = nil )

Description

Sorts the items of a numerically indexed table.

Parameters

SourceTable

(table) The table to sort.

Compare

(function) An optional comparison function to use while sorting the table. The function should be able to compare two values and return true if the two items are already sorted, or false if the items need to be swapped. If no function is specified, the less than operator (<) will be used to sort the items.

Returns

Nothing.


TextFile.ReadToString

string TextFile.ReadToString (

string Filename )

Description

Reads the contents of a text file and returns it as a string.

Parameters

Filename

(string) The full path to the text file.

Returns

(string) A string containing the contents of the text file. If an error occurs, a blank string "" is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


TextFile.ReadToTable

table TextFile.ReadToTable (

string Filename )

Description

Reads the contents of a text file into a table.

Parameters

Filename

(string) The full path to the text file.

Returns

(table) A table indexed by lines in the text file. Each table item contains one line of text from the file. If an error occurs, nil is returned. If the text file is empty, a table with an empty string is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


TextFile.WriteFromString

TextFile.WriteFromString (

string Filename,

string Text,

boolean Append = false )

Description

Writes a string of text to a text file.

Parameters

Filename

(string) The full path to the text file.

Note: If the file does not exist, it will be created.

Text

(string) The string of text to write.

Append

(boolean) Whether to append the string to the end of the text file:

VALUE | DESCRIPTION
true | Append the string to the end of the text file. (The text file must exist.)
false | Overwrite the current contents of the text file. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


TextFile.WriteFromTable

TextFile.WriteFromTable (

string Filename,

table Table,

boolean Append = false )

Description

Writes a table's contents out to a text file. The table should consist of one line of text per table item.

Parameters

Filename

(string) The full path to the text file.

Note: If the file does not exist, it will be created.

Table

(string) The table to write.

Append

(boolean) Whether to append the table's contents to the end of the text file:

VALUE | DESCRIPTION
true | Append the table's contents to the end of the text file. (The text file must exist.)
false | Overwrite the current contents of the text file. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


UninstallData.AddItem

UninstallData.AddItem (

number ItemType,

table ItemData )

Description

Adds an item to the uninstall configuration file.

Note: This action can only be used during the install and will not work during the uninstall.

Parameters

ItemType

(number) The type of item you want to add. This setting determines what the ItemData table should contain. Choose from:

CONSTANT | VALUE | DESCRIPTION
UNINDATA_MAIN | 0 | A main item such as: "DataFilePath" - The full path to the uninstall data file (*.dat). "CPRegKey" - The uninstall Registry key. "EXELocation" - The full path to the uninstall executable. "AppShortcutFolderPath" - The path to the application's shortcut folder. "UninstallReverseOrder" - Whether or not the files will be uninstalled in reverse order.
UNINDATA_FILES | 1 | A file to be uninstalled.
UNINDATA_SESSIONVARS | 2 | A session variable.
UNINDATA_SUPPORTFILES | 3 | A support file such as a primer file, image, plugin etc.
UNINDATA_SHORTCUTS | 4 | A shortcut (.lnk) file.
UNINDATA_FOLDERS | 5 | A folder to be uninstalled.
UNINDATA_SCRIPTS | 6 | An extra script to run during the uninstall.

ItemData

(table) A table whose contents depend upon the ItemType selected. Each table contains the following indexes:

UNINDATA_MAIN

KEY | TYPE | DESCRIPTION
Name | string | A main item such as: "DataFilePath" - The full path to the uninstall data file (*.dat). "CPRegKey" - The uninstall Registry key. "EXELocation" - The full path to the uninstall executable. "AppShortcutFolderPath" - The path to the application's shortcut folder. "UninstallReverseOrder" - Whether or not the files will be uninstalled in reverse order ("1" means they will be uninstalled in reverse order and "0" means that they will be uninstalled in the same order as they were installed). You can set this item by assigning the value to ItemData.Name.
Value | string | The value to assign to the main item. You can set this value by assigning it to ItemData.Value.

UNINDATA_FILES

KEY | TYPE | DESCRIPTION
Filename | string | The full path and filename of the file you want to add to the uninstall. You can assign this value to ItemData.Filename.
DecrementUsageCount | boolean | Whether the added file should have its usage count decremented when uninstalled. Assigning true to ItemData.DecrementUsageCount will decrement the count.
UnregisterCOM | boolean | Whether the added file should be unregistered when uninstalled. Assigning true to ItemData.UnregisterCOM will unregister the file.
UnregisterFont | boolean | Whether to unregister the file if it is a Font file when uninstalled. Assigning true to ItemData.UnregisterFont will unregister the font file.
FontDesc | string | The font description if the file is a TTF file. You can assign the description to ItemData.FontDesc.
BackupFile | string | The full path and filename of the backed up file, if the file was backed up during the install, or an empty string if no backup was performed. If needed you can assign the path to ItemData.BackupFile. NOTE: This value is for informational purposes only so a file could potentially be restored. Setup Factory does not automatically restore the backed up file.

UNINDATA_SESSIONVARS

KEY | TYPE | DESCRIPTION
Name | string | The session variable you want to add to the uninstall. For example, ItemData.Name = "%MyValue%".
Value | string | The contents of the session variable you want to add to the uninstall. This value can be assigned to ItemData.Value.

UNINDATA_SUPPORTFILES

KEY | TYPE | DESCRIPTION
Filename | string | The full path and filename of the support file you want to add to the uninstall. You can assign this file path to ItemData.Filename.

UNINDATA_SHORTCUTS

KEY | TYPE | DESCRIPTION
Filename | string | The full path and filename of the shortcut file (*.lnk) you want to add to the uninstall. You can assign the path to ItemData.Filename.

UNINDATA_FOLDERS

KEY | TYPE | DESCRIPTION
FolderPath | string | The full path and folder name of the folder you want to add to the uninstall. You can assign this path to ItemData.FolderPath.

UNINDATA_SCRIPTS

KEY | TYPE | DESCRIPTION
ID | string | A unique ID for the script, mainly used to identify it later.
Timing | number | The timing of the script (when it will be run during uninstall). Choose from 0=Before On Startup, 1=After On Startup, 2=Before On Pre Uninstall, 3=After On Pre Uninstall, 4=Before On Post Uninstall, 5=After On Post Uninstall, 6=Before On Shutdown, 7=After On Shutdown
Script | string | The script to run.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


UninstallData.GetConfigurationFile

string UninstallData.GetConfigurationFile (

)

Description

Gets the full path and filename of the uninstall configuration (.xml) file during the setup.

During installation the uninstall configuration file is not defined or created until right before the files are installed. Therefore this action must be called after that stage in the install.

During uninstall, it will always return the name of the xml file that it is currently working off of.

Parameters

None.

Returns

(string) The full path and filename of the uninstall configuration file. If this action fails, a blank string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


UninstallData.GetItem

table UninstallData.GetItem (

number ItemType,

string Identifier )

Description

Gets an item's details from the uninstall's configuration file.

Parameters

ItemType

(number) The type of item you want to get. The type of item determines what the Identifier is. Choose from:

CONSTANT | VALUE | DESCRIPTION
UNINDATA_MAIN | 0 | A main item such as: "DataFilePath" - The full path to the uninstall data file (*.dat). "CPRegKey" - The uninstall Registry key. "EXELocation" - The full path to the uninstall executable. "AppShortcutFolderPath" - The path to the application's shortcut folder. "UninstallReverseOrder" - Whether or not the files will be uninstalled in reverse order.
UNINDATA_FILES | 1 | A file's details.
UNINDATA_SESSIONVARS | 2 | A session variable.
UNINDATA_SUPPORTFILES | 3 | A support file's details such as a primer file, image, plugin etc.
UNINDATA_SHORTCUTS | 4 | A shortcut (.lnk) file's details.
UNINDATA_FOLDERS | 5 | A folder's details.
UNINDATA_SCRIPTS | 6 | An extra script to run during the uninstall.

Identifier

(string) The Identifier of the type you want to get. Below you will find the key identifiers to use:

CONSTANT | IDENTIFIER | DESCRIPTION
UNINDATA_MAIN | Name | The main item name such as: "DataFilePath" - The full path to the uninstall data file (*.dat). "CPRegKey" - The uninstall Registry key. "EXELocation" - The full path to the uninstall executable. "AppShortcutFolderPath" - The path to the application's shortcut folder. "UninstallReverseOrder" - Whether or not the files will be uninstalled in reverse order ("1" means they will be uninstalled in reverse order and "0" means that they will be uninstalled in the same order as they were installed).
UNINDATA_FILES | Filename | The full path and filename of the file.
UNINDATA_SESSIONVARS | Name | The session variable name.
UNINDATA_SUPPORTFILES | Filename | The full path to the support file such as a primer file, image, plugin etc.
UNINDATA_SHORTCUTS | Filename | The full path to the shortcut (.lnk) file.
UNINDATA_FOLDERS | FolderPath | The full path to the folder.
UNINDATA_SCRIPTS | ID | The unique ID for the script.

Returns

(table) A table containing the specified item's details. The table's contents are based upon the ItemType specified. One of the following tables is returned:

UNINDATA_MAIN

KEY | TYPE | DESCRIPTION
Name | string | The main item identifier such as "DataFilePath", "CPRegKey", "EXELocation", "AppShortcutFolderPath" or "UninstallReverseOrder."
Value | string | The value of the main item such as: "DataFilePath" - The full path to the uninstall data file (*.dat). "CPRegKey" - The uninstall Registry key. "EXELocation" - The full path to the uninstall executable. "AppShortcutFolderPath" - The path to the application's shortcut folder. You can access this item using ItemData.Value. "UninstallReverseOrder" - Whether or not the files will be uninstalled in reverse order ("1" means they will be uninstalled in reverse order and "0" means that they will be uninstalled in the same order as they were installed).

UNINDATA_FILES

KEY | TYPE | DESCRIPTION
Filename | string | The full path and filename of the file added to the uninstall. You can access this value using ItemData.Filename.
DecrementUsageCount | boolean | Whether the added file is set to have its usage count decremented when uninstalled. The returned value true means it will decrement the count. You can access this value using ItemData.DecrementUsageCount.
UnregisterCOM | boolean | Whether the added file is set to be unregistered when uninstalled. The value true means it will unregister the file. You can access this value using ItemData.UnregisterCOM.
UnregisterFont | boolean | Whether the file will be unregistered if it is a Font file. The value true to means it will unregister the font file. You can access this value using ItemData.UnregisterFont.
FontDesc | string | The font description if the file is a TTF file. You can access the description using ItemData.FontDesc.
BackupFile | string | The full path and filename of the backed up file if a backup was performed on the file during the install. If no backup was performed, an empty string is stored. You can access this value using ItemData.BackupFile. NOTE: This value is for informational purposes only so a file could potentially be restored. Setup Factory does not automatically restore the backed up file.

UNINDATA_SESSIONVARS

KEY | TYPE | DESCRIPTION
Name | string | The session variable name added to the uninstall. You can access this value using ItemData.Name.
Value | string | The contents of the session variable added to the uninstall. You can access this value using ItemData.Value.

UNINDATA_SUPPORTFILES

KEY | TYPE | DESCRIPTION
Filename | string | The full path and filename of the support file added to the uninstall. You can access this value using ItemData.Filename.

UNINDATA_SHORTCUTS

KEY | TYPE | DESCRIPTION
Filename | string | The full path and filename of the shortcut file (*.lnk) added to the uninstall. You can access this value using ItemData.Filename.

UNINDATA_FOLDERS

KEY | TYPE | DESCRIPTION
FolderPath | string | The full path and folder name of the folder added to the uninstall. You can access this value using ItemData.FolderPath.

UNINDATA_SCRIPTS

KEY | TYPE | DESCRIPTION
ID | string | The unique ID for the script. You can access this value using ItemData.ID.
Timing | number | The timing of the script (when it will be run during uninstall). This will be one of the following value: 0=Before On Startup, 1=After On Startup, 2=Before On Pre Uninstall, 3=After On Pre Uninstall, 4=Before On Post Uninstall, 5=After On Post Uninstall, 6=Before On Shutdown, 7=After On Shutdown. You can access this value using ItemData.Timing.
Script | string | The script set to be run to run. You can access this value using ItemData.Script.

If an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


UninstallData.GetItemList

table UninstallData.GetItemList (

number ItemType )

Description

Returns a numerically indexed table of identifiers given an uninstall data type.

Parameters

ItemType

(number) The type of item whose list you want to get. Choose from:

CONSTANT | VALUE | DESCRIPTION
UNINDATA_MAIN | 0 | A main item such as: "DataFilePath" - The full path to the uninstall data file (*.dat). "CPRegKey" - The uninstall Registry key. "EXELocation" - The full path to the uninstall executable. "AppShortcutFolderPath" - The path to the application's shortcut folder. "UninstallReverseOrder" - Whether or not the files will be uninstalled in reverse order.
UNINDATA_FILES | 1 | A file..
UNINDATA_SESSIONVARS | 2 | A session variable.
UNINDATA_SUPPORTFILES | 3 | A support file such as a primer file, image, plugin etc.
UNINDATA_SHORTCUTS | 4 | A shortcut (.lnk) file.
UNINDATA_FOLDERS | 5 | A folder.
UNINDATA_SCRIPTS | 6 | An extra script.

Returns

(table) A numerically indexed table of identifiers given the item's type. The following Identifiers can be returned:

ITEM TYPE | IDENTIFIER | DESCRIPTION
UNINDATA_MAIN | Name | The main item names such as: "DataFilePath", "CPRegKey", "EXELocation", "AppShortcutFolderPath" or "UninstallReverseOrder."
UNINDATA_FILES | Filename | The full path and filenames of the files.
UNINDATA_SESSIONVARS | Name | The session variable names.
UNINDATA_SUPPORTFILES | Filename | The full paths to the support files such as a primer files, images, plugins etc.
UNINDATA_SHORTCUTS | Filename | The full paths to the shortcut (.lnk) files.
UNINDATA_FOLDERS | FolderPath | The full paths to the folders.
UNINDATA_SCRIPTS | ID | The unique IDs for the scripts.

If an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


UninstallData.RemoveItem

UninstallData.RemoveItem (

number ItemType,

string Identifier )

Description

Removes an item from the uninstall's configuration file.

Note: This action is only supported during the install, and will not work in the uninstall.

Parameters

ItemType

(number) The type of item that you want to remove. The type of item determines what the Identifier is. Choose from:

CONSTANT | VALUE | DESCRIPTION
UNINDATA_MAIN | 0 | A main item such as: "DataFilePath" - The full path to the uninstall data file (*.dat). "CPRegKey" - The uninstall Registry key. "EXELocation" - The full path to the uninstall executable. "AppShortcutFolderPath" - The path to the application's shortcut folder. "UninstallReverseOrder" - Whether or not the files will be uninstalled in reverse order.
UNINDATA_FILES | 1 | A file to be uninstalled.
UNINDATA_SESSIONVARS | 2 | A session variable.
UNINDATA_SUPPORTFILES | 3 | A support file such as a primer file, image, plugin etc.
UNINDATA_SHORTCUTS | 4 | A shortcut (.lnk) file.
UNINDATA_FOLDERS | 5 | A folder to be uninstalled.
UNINDATA_SCRIPTS | 6 | An extra script to run during the uninstall.

Identifier

(string) The Identifier of the type you want to remove. Below you will find the key identifiers to use:

CONSTANT | IDENTIFIER | DESCRIPTION
UNINDATA_MAIN | Name | The main item name such as: "DataFilePath" - The full path to the uninstall data file (*.dat). "CPRegKey" - The uninstall Registry key. "EXELocation" - The full path to the uninstall executable. "AppShortcutFolderPath" - The path to the application's shortcut folder. "UninstallReverseOrder" - Whether or not the files will be uninstalled in reverse order.
UNINDATA_FILES | Filename | The full path and filename of the file.
UNINDATA_SESSIONVARS | Name | The session variable name.
UNINDATA_SUPPORTFILES | Filename | The full path to the support file such as a primer file, image, plugin etc.
UNINDATA_SHORTCUTS | Filename | The full path to the shortcut (.lnk) file.
UNINDATA_FOLDERS | FolderPath | The full path to the folder.
UNINDATA_SCRIPTS | ID | The unique ID for the script.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


UninstallData.SetConfigurationFile

UninstallData.SetConfigurationFile (

string Filename )

Description

Sets the name of the uninstall configuration (.xml) file during the setup. This allows you to manually change the uninstall configuration file that the data will be written to.

During installation the uninstall configuration file is not defined or created until right before the files are installed. Therefore this action must be called before that stage in the install.

Note: This action has no effect if called during the uninstall.

Parameters

Filename

(string) The full path and filename of the uninstall configuration file you want to use. This file should be in XML format (*.xml).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Close

Window.Close (

number WndHandle,

number Method = CLOSEWND_SENDMESSAGE )

Description

Closes a specific window on the user's desktop.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Method

(number) How to close the window. Choose from:

CONSTANT | VALUE | DESCRIPTION
CLOSEWND_SENDMESSAGE | 0 | Send the program a WM_CLOSE message. This is exactly like clicking the "Close" button on the window's title bar. (Default)
CLOSEWND_TERMINATE | 1 | Immediately terminate the program's process. The state of global data maintained by the program's dynamic-link libraries (DLLs) may be compromised if this option is used. (When this option is selected, the Setup Factory installation calls the Windows API function "TerminateProcess" to immediately terminate the specified program.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.EnumerateProcesses

table Window.EnumerateProcesses (

boolean TopLevel = true )

Description

Returns a table containing a list of all the currently running processes and their associated window handles.

Parameters

TopLevel

(boolean) Whether to return information from top level windows only:

VALUE | DESCRIPTION
true | Return the list for top level windows only. (Default)
false | Return the list for all available windows.

Note: In order for a window to be classified as a top level window, it must not have an owner window and must be visible.

Returns

(table) A table of window handles and the processes they belong to. In this table the window handles are the keys, and the values are the paths to the executables that spawned the processes. If an error occurs, or there were no processes (there should always be processes) nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Window.EnumerateTitles

table Window.EnumerateTitles (

boolean TopLevel = true )

Description

Returns a table containing the window handles and window titles of all of the open windows on the system.

Parameters

TopLevel

(boolean) Whether to return information from top level windows only:

VALUE | DESCRIPTION
true | Return the list for top level windows only. (Default)
false | Return the list for all available windows.

Note: In order for a window to be classified as a top level window, it must not have an owner window and must be visible.

Returns

(table) A table indexed by window handles, each containing its window title. If an error occurs or there are no windows, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Window.GetPos

table Window.GetPos (

number WndHandle )

Description

Returns the X and Y screen coordinates of a window in pixels. This coordinate refers to the upper left hand corner of the window relative to the screen.

Note: The upper left hand corner of the screen has X and Y coordinates of 0.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

(table) A table containing the window's current coordinates, indexed by values X and Y. If the window cannot be found or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Window.GetSize

table Window.GetSize (

number WndHandle )

Description

Returns the pixel dimensions of a window.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

(table) A table containing the window's pixel dimensions, indexed by values "Width" and "Height". If the window cannot be found, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Window.Hide

Window.Hide (

number WndHandle )

Description

Hides a specific window given it's window handle.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Maximize

Window.Maximize (

number WndHandle )

Description

Maximizes a specific window given it's window handle. This is the same as clicking the "Maximize" button on the title bar of a window.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Minimize

Window.Minimize (

number WndHandle )

Description

Minimizes a specific window given it's window handle. This is the same as clicking the "Minimize" button on the title bar of a window.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Restore

Window.Restore (

number WndHandle )

Description

Restores a specific window given it's window handle. Restoring means that if the window is currently maximized or minimized, the window will be re-sized to it's original size and position.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.SetOrder

Window.SetOrder (

number WndHandle,

number InsertAfter )

Description

Sets the z-order of a window relative to other visible windows on the system. This action can be used to control the order of overlapping windows on the desktop, so that a particular window displays on top, or behind another. The top-most window has the highest z-order.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

InsertAfter

(number) The handle of the window to precede the window specified in WndHandle. Alternatively, you can use one of the following constants:

CONSTANT | VALUE | DESCRIPTION
HWND_BOTTOM | 1 | Places the window at the bottom of the z-order. If the WndHandle parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows.
HWND_NOTOPMOST | -2 | Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window. This window will be the topmost window until it loses focus.
HWND_TOP | 0 | Places the window at the top of the z-order.
HWND_TOPMOST | -1 | Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated (loses focus).

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.SetPos

Window.SetPos (

number WndHandle,

number X,

number Y )

Description

Sets the X and Y pixel coordinates of a specific window relative to the screen.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

X

(number) The new X pixel coordinate (horizontal position) to set for the window. This is the X coordinate of the upper left hand corner of the window relative to the screen.

Y

(number) The new Y pixel coordinate (vertical position) to set for the window. This is the Y coordinate of the upper left hand corner of the window relative to the screen.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.SetSize

Window.SetSize (

number WndHandle,

number Width,

number Height )

Description

Sets the size of a specific window given it's window handle.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Width

(number) The new width of the window in pixels.

Height

(number) The new height of the window in pixels.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.SetText

Window.SetText (

number WndHandle,

string Text )

Description

Sets the title text for a specific window. This text will be displayed in the window's title bar and task bar.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Text

(string) The text to display.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Window.Show

Window.Show (

number WndHandle )

Description

Shows a specific window given it's window handle. This action can be used to "show" a window after a Window.Hide action was performed.

Parameters

WndHandle

(number) The integer value that represents the specific window on the user's desktop. (Commonly referred to as an hWnd.)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.Count

number XML.Count (

string XMLPath,

string ElementName )

Description

Counts the number of elements below a given XML path that match a given element name.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose children you want to count.

ElementName

(string) The element name (tag name) that you want to search for. Only elements that match will be counted. Use * to match any name.

Returns

(number) The number of matching child elements found. If an error occurs, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


XML.GetAttribute

string XML.GetAttribute (

string XMLPath,

string AttributeName )

Description

Returns the value of an element's attribute.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose attribute names you want to retrieve.

AttributeName

(string) The full path to the element whose attribute you want to retrieve.

Returns

(string) The value of the specified element's attribute. If an element has no attribute or an error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


XML.GetAttributeNames

table XML.GetAttributeNames (

string XMLPath )

Description

Returns the names of an element's attributes in a numerically indexed table.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose attribute names you want to retrieve.

Returns

(table) A numerically indexed table containing the names of the specified element's attributes. If the element doesn't contain any attributes or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


XML.GetElementNames

table XML.GetElementNames (

string XMLPath,

boolean FullPaths = false,

boolean IncludeIndices = false )

Description

Returns a numerically indexed table containing the names of all child elements contained within a specific element.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose child elements you want to find.

FullPaths

(boolean) Whether to return the full paths of the child elements, or just the element names:

VALUE | DESCRIPTION
true | Return the full paths of the child elements.
false | Return just the element names. (Default)

IncludeIndices

(boolean) Whether to append the delimiter and index (e.g. ":3") to each element name.

VALUE | DESCRIPTION
true | Append the delimiter to each element name.
false | Don't append the delimiter. (Default)

Returns

(table) A numerically indexed table containing the names of all child elements contained within the specified element. If there are no child elements or an error occurs, nil is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


XML.GetElementXML

string XML.GetElementXML (

string XMLPath )

Description

Returns the raw XML of an element, i.e. the plain-text XML code for the element and all of its children.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose XML you want to retrieve.

Returns

(string) The XML code for the entire element and all of its children. If the element doesn't exist, or an error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


XML.GetValue

string XML.GetValue (

string XMLPath )

Description

Returns the value of an element.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose value you want to retrieve.

Returns

(string) The value of the specified element. If the element contains no value, or an error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


XML.GetXML

string XML.GetXML (

)

Description

Returns the currently loaded XML document as a string.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

None.

Returns

(string) A string containing the currently loaded XML document. If no document is loaded or an error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


XML.InsertXML

XML.InsertXML (

string XMLPath,

string Text,

number InsertionMode )

Description

Inserts raw XML code into a specific location in the currently loaded document.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The path to the element where you want to insert the XML text. You can insert the XML before this element, insert it after this element, or replace the element (and all its children) with the new XML text.

Text

(string) The XML text that you want to insert.

InsertionMode

(number) The insertion mode to use:

CONSTANT | VALUE | DESCRIPTION
XML.INSERT_BEFORE | 0 | Insert the new XML text before the specified element.
XML.INSERT_AFTER | 1 | Insert the new XML text after the specified element.
XML.REPLACE | 2 | Replace the specified element's XML text with the new XML text.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.Load

XML.Load (

string Filename )

Description

Loads an XML file into memory so it can be processed.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

Filename

(string) The full path to the XML file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.RemoveAttribute

XML.RemoveAttribute (

string XMLPath,

string AttributeName )

Description

Removes a specific attribute from an element.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The path to the element whose attribute you want to remove.

AttributeName

(string) The name of the attribute you want to remove.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.RemoveElement

XML.RemoveElement (

string XMLPath )

Description

Removes a specific element (and its children) from the currently loaded XML document.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The path to the element you want to remove.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.Save

XML.Save (

string Filename )

Description

Saves the currently loaded XML document to a file.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

Filename

(string) The full path for the XML file.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.SetAttribute

XML.SetAttribute (

string XMLPath,

string AttributeName,

string AttributeValue )

Description

Sets the value of an element's attribute.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The path to the element whose attribute you want to set.

AttributeName

(string) The name of the attribute you want to set.

AttributeValue

(string) The value you want the attribute to have.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.SetValue

XML.SetValue (

string XMLPath,

string Value,

boolean WriteCDATA = false )

Description

Sets the value of an element.

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

XMLPath

(string) The full path to the element whose value you want to set.

Value

(string) The value you want the element to have.

WriteCDATA

(boolean) Whether to write the data as a CDATA section:

VALUE | DESCRIPTION
true | Write the data as a CDATA section.
false | Don't write the data as CDATA. (Default)

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


XML.SetXML

XML.SetXML (

string Text )

Description

Sets the currently loaded XML document to the contents of a string (overwriting its current contents).

Note: For more information on the XML actions, see the XML Actions Concepts topic.

Parameters

Text

(string) The XML document. This will replace the contents of the currently loaded XML document.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Error Codes

Actions

Overview Alphabetical List Error Codes

The following is a categorical list of all of the error codes that may be returned when calling actions in Setup Factory:

Note: All of the error code messages are stored in a table called _tblErrorMessages and can be accessed by their error code index. For example, accessing the table index _tblErrorMessages[1000] will access the error code string "The specified file could not be found."

(9999) Unknown Error Codes

(1000-1099) File Related

(1100-1199) Control Related

(1400-1499) Status Dialog Related

(1500-1599) INI File Related

(1600-1699) Registry Related

(1700-1799) List Box Related

(1800-1899) System Related

(1900-1999) Text File Related

(2000-2099) Window Related

(2100-2199) Drive Related

(2200-2299) Folder Action Related

(2300-2399) Shell Action Related

(2400-2499) DLL Related

(2500-2599) HTTP Related

(2700-2799) Dialog Related

(2800-2899) Application Related

(2900-2999) Internal Function Related

(3000-3099) String Related

(3100-3199) Scrolling Text Related

(3200-3299) Select Packages

(3300-3399) Math Related

(3400-3499) Service Related

(3500-3599) ODBC Related

(4200-4299) MSI Related

(34000-34099) Crypto Related

(37000-37099) XML Related

Unknown Error Codes (9999)

9999

"Unknown error."

File Related (1000-1099)

1000

"The specified file could not be found."

1001

"Failed to load file."

1002

"The specified path was not found."

1003

"The .exe file is invalid (non-Win32 .exe or error in .exe image)."

1004

"The operating system denied access to the specified file."

1005

"The file name association is incomplete or invalid."

1006

"The DDE transaction could not be completed because other DDE transactions were being processed."

1007

"The DDE transaction failed."

1008

"The DDE transaction could not be completed because the request timed out."

1009

"The specified dynamic-link library was not found."

1011

"There is no application associated with the given file name extension. This error will also be returned if you attempt to print a file that is not printable."

1012

"There was not enough memory to complete the operation."

1013

"File execution failed."

1014

"A sharing violation occurred."

1015

"Could not determine viewer class name."

1016

"Could not determine viewer command line."

1017

"Associated viewer was not an executable file."

1018

"Associated viewer executable does not exist."

1019

"Invalid source specified."

1020

"Invalid destination specified."

1021

"Source file(s) does not exist."

1022

"Destination directory does not exist."

1023

"Failed to copy one or more files."

1024

"Failed to delete one or more files."

1025

"Failed to schedule delete on reboot."

1026

"Failed to schedule move on reboot."

1027

"Operation aborted by user."

1028

"An error occurred while calling the callback function."

1029

"Error, the callback function could not be found."

1030

"Could not get the size of the version information."

1031

"Could not get the file version information."

1032

"The specified filename contains invalid characters."

1033

"The destination file already exists."

1034

"An unknown error occurred."

1035

"Run on reboot command failed, could not open key."

1036

"Run on reboot command failed, could not set value."

1037

"Could not set the file's attributes."

1038

"Could not set file's compressed attribute."

1039

"Could not create destination Folder."

1040

"Could not create a backup of one or more files."

1041

"Out of memory."

1043

"Failed to save file."

1045

"File execution failed, elevation required."

Note: This return code is only valid on Windows Vista or later.

Control Related (1100-1199)

1100

"The specified control could not be found."

1106

"Could not display control."

1107

"File is too large to read."

1108

"The specified file could not be opened."

1115

"Exception thrown by internal control."

1118

"Action cannot be performed on disabled control."

1150

"There is no current screen."

1151

"There is no control with the specified ID on the current screen."

1153

"The specified control is of the wrong type for this action."

Status Dialog Related (1400-1499)

1400

"Could not show status dialog."

1401

"Could not hide status dialog."

1402

"Could not set the status text on the status dialog."

1403

"Could not set the progress meter's range on the status dialog."

1404

"Could not set the progress meter's position on the status dialog."

1405

"Could not set the message text on the status dialog."

1406

"Could not set the title text on the status dialog."

1407

"Could not get the position of the progress meter."

INI File Related (1500-1599)

1500

"Could not delete the specified INI file section."

1501

"Could not delete the specified INI file value."

1502

"Could not set the specified value."

Registry Related (1600-1699)

1600

"Could not create the specified Registry key."

1601

"Could not delete the specified Registry key."

1602

"Could not delete the specified Registry value."

1603

"The specified sub key does not exist."

1604

"Could not get the sub key names."

1605

"Could not get the specified value's data."

1606

"Could not get the value names."

1607

"Could not get the registry value's type."

1608

"Could not set the specified registry value's data."

List Box Related (1700-1799)

1700

"Could not add item to List Box control."

1701

"Could not insert item into List Box control."

1702

"Index out of range."

System Related (1800-1899)

1800

"Could not get the OS Version information."

1801

"Could not reboot system. OS information not available."

1802

"Failure in LoadLibrary()."

1803

"GetProcAddress failed."

1804

"Failure code returned by DllRegisterServer."

1805

"Error in call to LoadTypeLib."

1806

"Error in call to RegisterTypeLib."

1807

"Error, font name cannot be empty."

1808

"Invalid font name."

1809

"Failed to add font to system font table."

1810

"Failed to add font to registry."

1811

"Failed to remove font from system font table."

1812

"Failed to remove font from registry."

1813

"Could not retrieve user information."

1814

"Unknown date format specified."

1815

"Unknown time format specified."

1816

"Unable to determine default language ID."

1817

"Unable to determine display info."

1818

"The server was unable to complete the registration of all the type libraries used by its classes."

1819

"The server was unable to complete the registration of all the object classes."

1820

"The server was unable to remove the entries of all the type libraries used by its classes."

1821

"The server was unable to remove the entries of all the object classes."

1822

"Failure code returned by DllUnregisterServer."

1823

"Could not reboot system."

1824

"Error, cannot use system restore while running in safe mode."

1825

"Error, the disk is full and system restore has been put into standby."

1826

"Error, the pending file rename operation already exists."

1827

"An internal error has occurred."

1828

"Error invalid sequence number."

1829

"The system restore service is disabled."

1830

"Error, the system restore operation has timed out."

1831

"Failed to access the number of running processes."

1832

"Failed to enumerate the processes."

1833

"Failed to get the process handle."

Text File Related (1900-1999)

1900

"Could not open text file."

1901

"The text file is too large to be read."

1902

"Error, could not save text file."

Window Related (2000-2099)

2000

"Error, window handle is not valid."

2001

"Error, could not hide window."

2002

"Error, could not maximize window."

2003

"Error, could not minimize window."

2004

"Error, could not restore window."

2005

"Error, could not show window."

Drive Related (2100-2199)

2100

"Error, could not eject drive, action not supported."

2101

"Error, could not calculate free space."

2102

"Error, could not calculate total size."

2103

"Error, could not calculate used space."

2104

"Failed to get volume information."

Folder Action Related (2200-2299)

2200

"Could not create folder."

2201

"The specified folder does not exist."

2202

"The specified path does not point to a folder."

2203

"Could not delete folder."

2204

"Could not set the current folder."

2205

"The destination folder already exists."

2206

"The folder name contains invalid characters."

2207

"Could not delete base folder."

Shell Action Related (2300-2399)

2300

"Could not create the folder for the shortcut."

2301

"Could not create the link for the shortcut."

2302

"Error, the shortcut description is longer then 250 characters."

2303

"Shortcut could not be deleted."

2304

"Unknown shell folder."

2305

"The folder returned is invalid."

DLL Related (2400-2499)

2400

"Failed to load the specified DLL."

2401

"Failed to find the specified function within the DLL."

HTTP Related (2500-2599)

2500

"Failed to create the Internet session."

2501

"Failed to create the HTTP connection."

2502

"Could not open request."

2503

"Send request failed."

2504

"Could not open the destination file for writing."

2505

"Invalid HTTP response from server."

2506

"An error occurred when downloading information from the server."

2507

"An error occurred while trying to write to the destination file."

2508

"The user has aborted the HTTP action."

2510

"An error occurred when trying to write to memory. (Out of memory?)"

2511

"An error occurred when trying to set the proxy username."

2512

"An error occurred when trying to set the proxy password."

2513

"The request could not be understood by the server. (Bad Syntax)"

2514

"Access is forbidden."

2515

"The requested URL was not found on the server."

2516

"An internal server error has occurred."

2517

"The server is at full capacity."

Dialog Related (2700-2799)

2700

"Could not register window class to create splash dialog."

2702

"Could not create image splash dialog."

2703

"Dialogs cannot be displayed during a silent install or uninstall."

Application Related (2800-2899)

2800

"An error occurred getting the current screen name. No current screen."

2801

"Could not load value."

2802

"Could not save value."

2803

"Error, could not get the application's window handle."

2820

"There is no screen currently displayed."

2821

"Screen jump failed."

2850

"Package not found."

2860

"Invalid uninstall configuration file."

2861

"Invalid table data."

2862

"Invalid uninstall data item type."

2863

"Uninstall data item not found."

2864

"Action not available during uninstall."

Internal Function Related (2900-2999)

2900

"An internal error occurred resolving the specified function."

2901

"A runtime error occurred while calling the function."

2902

"A memory allocation error occurred while calling the function."

String Related (3000-3099)

3000

"An invalid index has been specified. Indices must be greater than or equal to -1."

3001

"The specified path is longer than MAX_PATH, or 260 characters."

Scrolling Text Related (3100-3199)

3100

"Invalid scrolling text mode."

Select Packages (3200-3299)

3200

"The specified category could not be found."

3201

"Could not set the category's properties."

Math Related (3300-3399)

3300

"The specified math value is not valid for the given function."

Service Related (3400-3499)

3401

"An error occurred while trying to iterate the services."

3402

"An error occurred while trying to query the services."

3403

"The service could not be found."

3404

"The continue command failed."

3405

"The stop command failed."

3406

"The start command failed."

3407

"The pause command failed."

3408

"The delete command failed."

3409

"The create command failed."

3410

"The handle to the specified service control manager database does not have access."

3411

"A circular service dependency was specified."

3412

"The display name already exists in the service control manager database either as a service name or as another display name."

3413

"The handle to the specified service control manager database is invalid."

3414

"The specified service name is invalid."

3415

"A parameter that was specified is invalid."

3416

"The user account name specified does not exist."

3417

"The specified service already exists in this database."

ODBC Related (3500-3599)

3500

"A general ODBC error occurred."

3501

"The buffer length was invalid."

3502

"The hWnd value was invalid."

3503

"The string value was invalid."

3504

"The request type specified was invalid."

3505

"The component was not found in the registry."

3506

"The Driver argument was invalid, it could not be found in the registry."

3507

"The was an invalid keyword=name pair."

3508

"Invalid DSN."

3509

"Invalid INF."

3510

"The operation requested by the Request parameter failed."

3511

"An invalid path was specified."

3512

"An error occurred while trying to load the driver or translator library."

3513

"An invalid list of keyword=name pairs was used."

3514

"Invalid log file."

3515

"The request was canceled by the end user."

3516

"An error occurred while trying to increment or decrement the component usage count."

3517

"Failed to create the DSN."

3518

"Failed to write sysinfo."

3519

"Failed to remove DSN."

3520

"A function failed because there was not enough memory."

3521

"The output string was truncated."

3522

"Failed to load the ODBC DLL."

3523

"The GetProc command failed."

MSI Related (4200-4299)

4200

"Failed to load MSI.DLL. Windows Installer is not installed."

4201

"Failed to load function from MSI.DLL."

4203

"The user has cancelled the installation."

4204

"A fatal error occurred during the installation."

4205

"Installation suspended, incomplete."

4206

"Error unknown product."

4207

"Error unknown feature."

4208

"Error unknown component."

4209

"Error unknown property."

4210

"The handle is in an invalid state."

4211

"MSI configuration data is invalid."

4212

"The component qualifier is not present."

4213

"The installation source for this product is not available."

4214

"The product is uninstalled."

4215

"The SQL query syntax is invalid or unsupported."

4216

"The record field does not exist."

4217

"The Windows Installer service could not be accessed."

4218

"Error package version."

4219

"Another installation is already in progress."

4220

"This installation package could not be opened."

4221

"This installation package could not be opened, it appears to be invalid."

4222

"There was an error starting the Windows Installer service user interface."

4223

"There was an error opening installation log file."

4224

"The language of this installation package is not supported by your system."

4225

"This installation is forbidden by system policy."

4226

"The function could not be executed."

4227

"The function failed during execution."

4228

"An invalid or unknown table was specified."

4229

"The data supplied is the wrong type."

4230

"Data of this type is not supported."

4231

"The Windows Installer service failed to start."

4232

"The Temp folder is either full or inaccessible."

4233

"This installation package is not supported on this platform."

4234

"The install component is not used on this machine."

4235

"There was an error applying transforms."

4236

"This patch package could not be opened."

4237

"This patch package could not be opened, it appears to be invalid."

4238

"This patch package cannot be processed by the Windows Installer service, it is unsupported."

4239

"Another version of this product is already installed."

4240

"Invalid command line argument."

4241

"Installation from a Terminal Server client session is not permitted for the current user."

4242

"The installer has initiated a restart."

4243

"The installer cannot install the upgrade patch because the program being upgraded may be missing or the upgrade patch updates a different version of the program."

4244

"The patch package is not permitted by system policy."

4245

"One or more customizations are not permitted by system policy."

4246

"Windows Installer does not permit installation from a Remote Desktop Connection."

4247

"The patch package is not a removable patch package."

4248

"The patch could not be applied to this product. Unknown patch."

4249

"A valid sequence could be found for the set of patches."

4250

"Patch removal was disallowed by policy."

4251

"The XML patch data is invalid."

4252

"Administrative user failed to apply patch for a per-user managed or a per-machine application that is in advertise state."

4253

"An invalid parameter has been passed to the function."

4254

"A buffer is to small to hold all of the data."

4255

"A restart is required to complete the install."

4256

"The MSI file is invalid, or does not contain a valid version of specific information."

4257

"The MSI file contains invalid data."

4258

"An unexpected error has occurred."

4259

"An invalid handle has been used."

Crypto Related (34000-34099)

34000

"String does not contain valid base-64 encoded data."

34001

"Error while attempting to decode base-64 encoded string (usually means string is corrupt - missing bytes in string?)."

34002

"Invalid file header - not an Indigo Rose blowfish file."

34003

"Incompatible blowfish file. (The file has either been damaged or it uses an incompatible block padding scheme.)"

XML Related (37000-37099)

37000

"Error loading XML file."

37001

"Error saving XML file."

37002

"No valid XML document loaded. (The document is empty or not well formed.)"

37003

"The specified XML path is not valid or was not found."

37004

"An error occurred while trying to set the value."

37005

"An error occurred while trying to set the attribute."

37006

"Invalid attribute name. (Attribute names cannot contain spaces.)"

37007

"The specified element could not be removed."

37008

"The specified attribute could not be removed."

37009

"There are no elements below the specified XML path."

37010

"The element at the specified XML path does not have any attributes."

37011

"An error occurred while trying to insert XML."

37012

"Invalid insertion mode."


Build Settings - Overview

Build Settings

Overview Setup File Constants Code Signing Resources Pre/Post Build

The Build Settings dialog is where you can make decisions that control the generation of your final install executable. Some of these settings include: the location you wish to output the file; the platform of the setup file; the build configuration you wish to use; design-time constants that you wish to recognize during the build process; the code signing settings to sign your setup; custom resource stamping; and any programs you wish to run before or after the build process.

To access the Build Settings dialog, choose Publish > Settings from the program menu.

Tip: To reduce the build time on large setups, try disabling the output progress information during the build. See the Report status during build setting in the Build Preferences.

Whether to output progress information during the build of the setup. Unchecking this option decreases the build time of the setup. Report status during build

The Build Settings contain the following five categories:

  • Setup File

  • Constants

  • Code Signing

  • Resources

  • Pre/Post Build


Setup File

Build Settings

Overview Setup File Constants Code Signing Resources Pre/Post Build

Build configuration:

The build configuration you want to use when generating your final installation. The dropdown contains all of the current build configurations. A build configuration contains all previously saved information on the Setup File, Constants, Code Signing, Resources, and Pre/Post Build tabs. Beyond the information on the build settings dialog, build configurations also include dependency modules, primer files, script files, plugins, serial number lists, file lists, and folder reference lists.

Add ( )

Opens the New Build Configuration dialog where you can create a new build configuration in your project.

Remove ( )

Removes the current build configuration from your project.

Note: There must be at least one build configuration in your project.

Rename ( )

Renames the current build configuration.

Location

Output folder:

The directory that you want the setup executable saved to when it is finished building. You can click the Browse button to select an output folder.

Setup filename:

The name you want to give your setup file. This can be setup.exe, install.exe or anything else that you want.

Size

Segment size:

The segment size of the setup executable that will be generated. Choose from:

Web (Single File)

Generate the setup executable as one file.

Smallest segment

Generate the setup executable as the smallest possible segments for distribution.

74 Minute CD-ROM (650 MB)

Generate the setup executable as 650 MB segments suitable for copying to 74 minute CD-ROMs.

80 Minute CD-ROM (700 MB)

Generate the setup executable as 700 MB segments suitable for copying to 80 minute CD-ROMs.

DVD

Generate the setup executable as 2 GB segments suitable for copying to 4.7 gig DVD's.

Custom

Generate the setup executable as segments of the size specified in Custom size.

Note: If you are generating a multi-segment install (not Web (Single File)), you must use the /W command line option if you want the setup to wait for return (Web (Single File) installs always wait for return). Generally you shouldn't wait for return on very large multi-segment installs as memory errors may occur.

Custom size (bytes):

The size in bytes that you want for each setup executable segment.

Note: Segment sizes must be large enough to accommodate the Setup Factory runtime and any primer files that have been added. If the selected size is smaller than Setup Factory requires, it will automatically increase the value.

When building a multi-segment install, each segment must be less than 2 gigabytes (2147483648 bytes) in size.

Compression

LZMA low

Use a fast compression ratio (less than LZMA high).

LZMA high

Use a normal compression ratio (greater than LZMA low).

LZMA2 low

Use a fast compression ratio (less than LZMA2 high). LZMA2 is an improved version of LZMA that is faster and has better multithreading support (see CPU threads setting).

LZMA2 high

Use a normal compression ratio (greater than LZMA2 low). LZMA2 is an improved version of LZMA that is faster and has better multithreading support (see CPU threads setting).

Dictionary size:

The dictionary size for the chosen compression method (LZMA low, LZMA high, LZMA2 low or LZMA2 high). The higher the dictionary size, the better the compression ratio.

Note: For LZMA and LZMA2 compression the memory use is about 10 times more than the dictionary size (in megabytes). For decompression it's about equal to the dictionary size.

Note: Increasing the dictionary size may result in a slower build time and require more memory usage.

Word size:

The length of words to use to find identical sequences of bytes for compression. Larger word sizes can significantly increase the compression ratio when files contain long identical sequences of bytes, however it also affects the compression and decompression speed.

CPU threads:

The number of threads to use for compression. LZMA has a maximum of 2 threads while LZMA2 has a maximum of 16.

Note: Increasing the number of threads also increases the memory usage.

Platform

The desired platform of your setup. The platform you select should be based on the platform of the application or files you are distributing.

Note: If your setup includes dependency modules, plugins, or any other resources, you must also ensure you have selected the correct platform version of those resources.

Tip: If you plan to distribute both 32-bit and 64-bit setup files for your application, it may be possible to create a single setup project for both platforms instead of separate project files. For minor differences between platform distributions, it may be beneficial to create build configurations containing the differing settings for each platform in order to maintain a single setup project file.

To start, create a build configuration containing all the settings required for one of the platforms, making note of any settings not controlled directly by build configurations that may need to be different. Such settings may require the creation of build constants in order for the information to be dynamically set at build time.

Once you've defined all of the settings for your first configuration, you can add a new one by copying all of the settings from your initial one and then modify it accordingly. See the Build Configurations section in Chapter 11: Building and Distributing of the user's guide for more information on build configurations.

Select one of the following platforms:

32-bit

Create a 32-bit setup file for a 32-bit compiled application/files.

Note: 32-bit setup files will run on both 32-bit and 64-bit operating systems.

64-bit

Create a 64-bit setup file for a 64-bit compiled application/files.

Note: 64-bit setup files will fail to run on 32-bit operating systems.

Note: UPX compression is not compatible with 64-bit, therefore 64-bit setups will in general be larger than their 32-bit equivalent.

Launch User

Collect launch user information

If checked, a series of session variables will be populated with the folders located in the user profile that launched the setup. The following variables are available:

%LaunchUserApplicationDataFolder%
%LaunchUserDesktopFolder%
%LaunchUserDomain%
%LaunchUserMyDocumentsFolder%
%LaunchUserMyMusicFolder%
%LaunchUserMyPicturesFolder%
%LaunchUserMyVideosFolder%
%LaunchUserName%
%LaunchUserStartFolder%
%LaunchUserStartProgramsFolder%
%LaunchUserStartupFolder%


Constants

Build Settings

Overview Setup File Constants Code Signing Resources Pre/Post Build

Build configuration:

The build configuration you want to use when generating your final installation. The dropdown contains all of the current build configurations. A build configuration contains all previously saved information on the Setup File, Constants, Code Signing, Resources, and Pre/Post Build tabs. Beyond the information on the build settings dialog, build configurations also include dependency modules, primer files, script files, plugins, serial number lists, file lists, and folder reference lists.

Add ( )

Opens the New Build Configuration dialog where you can create a new build configuration in your project.

Remove ( )

Removes the current build configuration from your project.

Note: There must be at least one build configuration in your project.

Rename ( )

Renames the current build configuration.

Constants

A list of all of the custom design-time constants available across all build configurations and their data values in the current build configuration.

Design-time constants are similar to variables, but instead of being converted to values at run time, design-time constants get converted at build time. We call them design-time constants because the names you give them only exist at design time. At build time, the name of each design-time constant is replaced by the value that was assigned to it.

Note: Design-time constants can be in any format you like. One recognizable format is the variable name in capitals surround by "#" characters. For example, #MYVAR#. However if you plan to use these design-time constants in action script, the names may be caught by the automatic syntax checker if certain characters are used that are part of the Lua language (such as "#"). In this case, it is best to use an alternate format such as _MYVAR.

Tip: There are also a number of built-in design-time constants that are available.

Add

Add a new design-time constant to all build configurations and define it's value in the current build configuration.

Remove

Remove the selected design-time constant from all build configurations.

Rename

Rename the selected design-time constant.

Note: This will only rename the constant on the build settings dialog. If you've previously referenced the current constant in your project, you must manually change those values to the new name.


Code Signing

Build Settings

Overview Setup File Constants Code Signing Resources Pre/Post Build

Tip: See the Code Signing Defaults section of the build preferences (Edit > Preferences, Code Signing) to configure default values when creating new projects.

Tip: If you want full control over the how the setup is code signed, you can leave all fields blank except for Tool location, and specify all options in the Other arguments field. When "SignTool.exe" is the selected tool, Setup Factory automatically passes the option "sign".

Build configuration:

The build configuration you want to use when generating your final setup. The drop down contains all of the current build configurations. A build configuration contains all previously saved information on the Setup File, Constants, Code Signing, Resources, and Pre/Post Build tabs. Beyond the information on the build settings dialog, build configurations also include dependency modules, primer files, script files, plugins, serial number lists, file lists, and folder reference lists.

Add ( )

Opens the New Build Configuration dialog where you can create a new build configuration in your project.

Remove ( )

Removes the current build configuration from your project.

Note: There must be at least one build configuration in your project.

Rename ( )

Renames the current build configuration.

Code sign setups

If checked, the setup and uninstall will be code signed during the build process using the settings below. See Authenticode Code Signing for more information.

Settings

Code signing tool:

The tool you want to use to digitally sign the setup. Choose from:

SignTool.exe

Use SignTool.exe to digitally sign the setup file. This tool could not be distributed, but is available in the \Bin folder of the Platform Software Development Kit (SDK). For more information, see MSDN: SignTool (Windows).

SignCode.exe

Use SignCode.exe to digitally sign the setup file. This tool could not be distributed, and only ships with the .NET Framework SDK version 1.0 and 1.1. For more information, see MSDN: File Signing Tool (Signcode.exe).

Tool location:

The full path and filename of the chosen code signing tool on your system (SignTool.exe or SignCode.exe). You can click the Browse button to select the file.

Certificate filename:

The full path and filename of the certificate to use when signing the setup file. If SignTool.exe is selected, this file must be a "Personal Information Exchange" file (*.PFX). If SignCode.exe is selected, this file must be a "Software Publisher Certificate" file (*.SPC). You can click the Browse button to select the file.

Tip: If your .PFX file is password protected, you must pass its value in the Other arguments field using the /p option. For example: /p "mypassword". For more information, see MSDN: SignTool (Windows).

Private key filename:

The full path and filename of the "Private Key" file (*.pvk) to use for signing. This file is only used when SignCode.exe is the selected tool. You can click the Browse button to select the file.

Timestamp URL:

The URL of a timestamp DLL on the Web such as: http://timestamp.verisign.com/scripts/timstamp.dll. If you do not want to timestamp the setup file, leave this field blank.

Description:

The description of the signed content.

Description URL:

A URL that provides further information about the signed content.

Other arguments:

Any additional options you would like to pass to the code signing tool. If you leave any of the above fields blank (except for tool location), you can pass their values as command line options. Setup Factory automatically passes the "sign" argument when "SignTool.exe" is the selected tool.


Resources

Build Settings

Overview Setup File Constants Code Signing Resources Pre/Post Build

Build configuration:

The build configuration you want to use when generating your final setup. The drop down contains all of the current build configurations. A build configuration contains all previously saved information on the Setup File, Constants, Code Signing, Resources, and Pre/Post Build tabs. Beyond the information on the build settings dialog, build configurations also include dependency modules, primer files, script files, plugins, serial number lists, file lists, and folder reference lists.

Add ( )

Opens the New Build Configuration dialog where you can create a new build configuration in your project.

Remove ( )

Removes the current build configuration from your project.

Note: There must be at least one build configuration in your project.

Rename ( )

Renames the current build configuration.

Custom Icon

Use custom icon

If checked, you can use a custom icon for the setup executable.

Path to local icon file:

The full path and filename of the icon file (.ico) to use for the setup executable. You can click the Browse button to select an icon file.

Custom Version Information

Stamp executable with custom information

If checked, you can stamp the setup executable with your own custom version information.

File version:

The file version. For example, "1.0.0.19". If you leave out any digits they will be replaced with zeros. If this field is empty, version "1.0.0.0" will be used.

Product version:

The product version. For example, "1.0.0.19". If you leave out any digits they will be replaced with zeros. If this field is empty, version "1.0.0.0" will be used.

Comments:

Comments about the product. Often this field is used for a company or product's Web page address, but it can be anything you want.

Company name:

Your company name. For example, "Indigo Rose Software."

Product name:

The name of the product. For example, "My Nifty Application."

Internal name:

The internal name of the product. Usually the same as the Product name.

File description:

A short description about the purpose of the published executable. For example, "My Nifty Application runtime."

Copyright:

A copyright notice for the product. For example, "Copyright © 2015 - Indigo Rose Software."

Trademarks:

Trademark notices for the product.

Private build:

Any 'private build' notes that may apply.

Special build:

Any 'special build' notes that may apply.


Pre_Post Build

Build Settings

Overview Setup File Constants Code Signing Resources Pre/Post Build

Build configuration:

The build configuration you want to use when generating your final installation. The dropdown contains all of the current build configurations. A build configuration contains all previously saved information on the Setup File, Constants, Code Signing, Resources, and Pre/Post Build tabs. Beyond the information on the build settings dialog, build configurations also include dependency modules, primer files, script files, plugins, serial number lists, file lists, and folder reference lists.

Add ( )

Opens the New Build Configuration dialog where you can create a new build configuration in your project.

Remove ( )

Removes the current build configuration from your project.

Note: There must be at least one build configuration in your project.

Rename ( )

Renames the current build configuration.

Run Before Build

Run program:

The fully qualified name of a file to execute before the build process begins. In other words, this is the complete drive, directory and filename of a program to run before the setup executable is generated. You can click the Browse button to select the file you want to execute.

Note: There is a known issue pertaining to running batch files whose source paths contain ampersand characters ('&'). To use this feature, ensure that the path to the batch file does not contain any ampersand character references.

Command line arguments:

Any command line arguments that should be passed to the program named in the Run program field.

Wait for program to finish running

Make Setup Factory wait until after the program has finished running before it continues. If not checked, Setup Factory will simply start the program and continue with the build process.

Run After Build

Run program:

The fully qualified name of a file to execute after the build process finishes. In other words, this is the complete drive, directory and filename of a program to run after the setup executable is generated. You can click the Browse button to select the file you want to execute.

Note: There is a known issue pertaining to running batch files whose source paths contain ampersand characters ('&'). To use this feature, ensure that the path to the batch file does not contain any ampersand character references.

Command line arguments:

Any command line arguments that should be passed to the program named in the Run program field.

Wait for program to finish running

Make Setup Factory wait until after the program has finished running before it continues. If not checked, Setup Factory will simply start the program and continue without waiting.


Controls - Overview

Controls

Overview Control Types

Controls are interactive objects that exist on screens to collect or present information. Some examples of controls are buttons, edit fields and combo boxes, each of which have their own unique features.

In order to respond to user interaction, each type of control fires unique notification messages to signal what type of interaction occurred with the control. Any control message that is fired from the screen can be detected on the On Ctrl Message event of the screen. This allows you to respond with actions at that exact moment.

Each control on a screen contains a unique identifier called a Control ID, for example CTRL_BUTTON_NEXT. This ID is used to determine exactly which control fired the notification message and which control message was fired. An example of a control message is MSGID_CLICKED.

In most cases, it is not necessary to manually interact with controls since much of the functionality is built into the available screen templates. However, sometimes further customization is required and controls offer the power and flexibility to accomplish a wide range of dynamic designs.


Control Types

Controls

Overview Control Types

Setup Factory's screens use a wide range of controls to collect data and display information to the user. Each type of control has its own notification messages and actions that allow you to interact with it.

The following control types are used on screens in Setup Factory:

  • Billboard

  • Button

  • Category

  • Check Box

  • Combo Box

  • Edit Field

  • Group Box

  • List Box

  • Progress Bar

  • Radio Button

  • Scrolling Text

  • Select Package

  • Static Text

  • Timer


Billboard

Billboard Control

Overview

The billboard control allows you to incorporate billboards (an image slideshow, or single images) on your custom screens or custom progress screens. The billboard control contains many settings that can be configured to suit your presentation, such as: background style, border style, image duration, resize modes, auto-start, looping, shuffle, image transition effects, and many more.

Additional features of the billboard control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

Note: Notification messages are not triggered when actions interact with this control.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by a billboard control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them.

e_MsgID

e_Details

Description

MSGID_CLICKED

nil

Fired when the billboard control is clicked.

MSGID_ONPLAY

nil

Fired when the billboard control begins to play.

MSGID_ONPAUSED

nil

Fired when the billboard control is paused.

MSGID_ONFINISHED

nil

Fired when the billboard control reaches the end. Note: If the Loop setting is selected, this message will not be fired.

MSGID_ONIMAGECHANGED

(number) Index - The 1-based index of the image that was changed to in the billboard (currently shown).

(string) FilePath - The full path to the image file that was changed to in the billboard (currently shown).

Fired each time the image changes in the billboard control.

Related Actions

The following actions are available for interacting with a billboard control:

DlgBillboard.AddImage

DlgBillboard.DeleteImage

DlgBillboard.FillFromFolder

DlgBillboard.GetCurrentImage

DlgBillboard.GetImageCount

DlgBillboard.GetImagePath

DlgBillboard.GetPos

DlgBillboard.GetProperties

DlgBillboard.GetSize

DlgBillboard.GoToImage

DlgBillboard.IsEnabled

DlgBillboard.IsVisible

DlgBillboard.Navigate

DlgBillboard.Pause

DlgBillboard.Play

DlgBillboard.SetEnabled

DlgBillboard.SetPos

DlgBillboard.SetProperties

DlgBillboard.SetSize

DlgBillboard.SetVisible


Button

Button Control

Overview

A button control is a visual component of a screen that can be clicked by the user and responded to with action script. Examples of button controls can be seen below:

Additional features of the button control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

Note: Notification messages are not triggered when actions interact with this control.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by a button control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them.

e_MsgID | e_Details | Description
MSGID_CLICKED | nil | Fired when the button was clicked.

Related Actions

The following actions are available for interacting with a button control:

DlgButton.GetProperties

DlgButton.SetProperties


Category

Category Control

Overview

A category is a type of control that is used within a select package control on a select packages screen. It is designed to group a number of packages and/or other categories together in a select package tree. If a parent category is selected by the user, all of the packages and categories within it will be selected as well.

Additional features of the category control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

The category control does not fire any notification messages.

Related Actions

The following actions are available for interacting with a category control:

DlgSelectPackages.GetCategoryProperties

DlgSelectPackages.SetCategoryProperties

DlgSelectPackages.UpdateDisplay


Check Box

Check Box Control

Overview

A check box control is a tool used to collect a true or false value from the user on a screen. This control contains two visual states. An example of a check box and its two states can be seen below:

A 'checked' check box control:

An 'unchecked' check box control:

Additional features of the check box control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

Note: Notification messages are not triggered when actions interact with this control.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by a check box control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them. For example, you can access the item "Checked" from this table by using e_Details.Checked.

e_MsgID | e_Details | Description
MSGID_CLICKED | (boolean) Checked - Whether the check box is checked or not. The value true means it is checked and false means it is not. | Fired when the check box was clicked.

Related Actions

The following actions are available for interacting with a check box control:

DlgCheckBox.GetProperties

DlgCheckBox.SetProperties


Combo Box

Combo Box Control

Overview

A combo box control, commonly referred to as a "drop down," can be used to present a list of selectable options while consuming a minimal amount screen space. A combo box is a combination of a drop down menu with an edit field to display the user's selection. An example of a combo box both in its normal and expanded view can be seen below:

A typical combo box control:

After clicking on the combo box to access its drop-down list:

Additional features of the combo box control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

Note: Notification messages are not triggered when actions interact with this control.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by a combo box control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them. For example, you can access the item "Text" from this table by using e_Details.Text.

e_MsgID | e_Details | Description
MSGID_ONCHANGED | (string) Text - The new text of the control | Fired when the text changes in the combo box edit field.
MSGID_ONSELCHANGED | (number) CurSel - The (1-based) index of the current selection. (string) Text - The text of the selected item. | Fired when the selection changes.

Related Actions

The following actions are available for interacting with a combo box control:

DlgComboBox.AddItem

DlgComboBox.GetItemData

DlgComboBox.GetItemText

DlgComboBox.GetProperties

DlgComboBox.InsertItem

DlgComboBox.RemoveItem

DlgComboBox.SetItemData

DlgComboBox.SetProperties


Edit Field

Edit Field Control

Overview

An edit field control is designed to gather textual input from the user such as a company name, file path or telephone number. An example of an edit field can be seen below:

Additional features of the edit field control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

Note: Notification messages are triggered when actions interact with this control.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by an edit field control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them. For example, you can access the item "Text" from this table by using e_Details.Text.

e_MsgID | e_Details | Description
MSGID_ONCHANGED | (string) Text - The new text of the control | Fired when the edit field's text changes.

Related Actions

The following actions are available for interacting with an edit field control:

DlgEditField.GetProperties

DlgEditField.SetProperties


Group Box

Group Box Control

Overview

A Group Box control displays a rectangle with optional caption text, that can be used to group other controls together on a screen. An example of a group box control can be seen below:

Note: This control does not respond to themes. Neither colored project themes nor overriding the project theme settings will change the look of this object.

Additional features of the group box control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

The group box control does not fire any notification messages.

Related Actions

The following actions are available for interacting with a group box control:

DlgGroupBox.GetProperties

DlgGroupBox.SetProperties


List Box

List Box Control

Overview

A list box control is a tool used to present a scrollable list of text items that can be selected by the user. There are two styles for this control, a standard list box and a checklist box. A checklist box is a standard list box with the addition of check boxes for each item. Other features of this control include the ability to select multiple items and sort them alphabetically. An example of a list box control and a checklist box can be seen below.

A 'normal' List Box control:

A 'checked' List Box control:

Additional features of the list box control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

Note: Notification messages are not triggered when actions interact with this control.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by a list box control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them. For example, you can access the item "Index" from this table by using e_Details.Index.

e_MsgID | e_Details | Description
MSGID_CLICKED | (number) Index - The index of the item that was clicked. (string) Text - The text of the item that was clicked. (boolean) Selected - The selected state of the item. (boolean) Checked - The checked state of the item. (This applies to Checklist box style) | Fired when an item in the list is clicked on.
MSGID_ONSELCHANGED | nil | Fired when the list box selection changes.

Related Actions

The following actions are available for interacting with a list box control:

DlgListBox.AddItem

DlgListBox.DeleteItem

DlgListBox.FindItem

DlgListBox.GetCount

DlgListBox.GetItemProperties

DlgListBox.GetProperties

DlgListBox.GetSelected

DlgListBox.GetSelectedCount

DlgListBox.InsertItem

DlgListBox.SetItemProperties

DlgListBox.SetProperties

DlgListBox.SetUpdate


Progress Bar

Progress Bar Control

Overview

A progress bar control is designed to provide a visual representation of the progress being made during some setup process. Contained within a progress bar is a progress meter that moves from left to right filling the bar. A couple of examples can be seen below:

A 'segmented' progress bar control:

A 'smooth' progress bar control:

Additional features of the progress bar control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

The progress bar control does not fire any notification messages.

Related Actions

The following actions are available for interacting with a progress bar control:

DlgProgressBar.GetPos

DlgProgressBar.GetProperties

DlgProgressBar.GetRange

DlgProgressBar.SetPos

DlgProgressBar.SetProperties

DlgProgressBar.SetRange

DlgProgressBar.SetStep

DlgProgressBar.Step


Radio Button

Radio Button Control

Overview

A radio button control is a tool used to collect a true or false value from the user on a screen. Similar to a check box, this control contains two visual states. The difference between a check box and a radio button is that only one radio button on a given screen can be selected at a time. An example of a radio button and its two states can be seen below:

A 'selected' radio button control:

An 'unselected' radio button control:

Additional features of the radio button control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

Note: Notification messages are not triggered when actions interact with this control.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by a radio button control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them. For example, you can access the item "Checked" from this table by using e_Details.Checked.

e_MsgID | e_Details | Description
MSGID_CLICKED | (boolean) Checked - Whether the radio button is selected or not. The value true means it is selected and false means it is not. | Fired when the control is clicked on.

Related Actions

The following actions are available for interacting with a radio button control:

DlgRadioButton.GetProperties

DlgRadioButton.SetProperties


Scrolling Text

Scrolling Text Control

Overview

A scrolling text control is designed to allow large amounts of text to be shown on a screen that would normally exceed the screen's dimensions. This is made possible using vertical and horizontal scroll bars, similar to those found on a common Web browser. This control accepts both plain text and HTML. An example of a scrolling text control can be seen below:

Additional features of the scrolling text control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

Note: Notification messages are not triggered when actions interact with this control.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by a scrolling text control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them. For example, you can access the item "Text" from this table by using e_Details.Text.

e_MsgID | e_Details | Description
MSGID_ONCHANGED | (string) Text - The new text of the control | Fired when the text changes (only in Text mode).
MSGID_ONNAVIGATE | (string) URL - The URL being navigating to. | Fired when an HTML navigation occurs. (only in HTML mode).
MSGID_ONLOADED | (string) URL - The URL that was loaded. | Fired when an HTML navigation completes. (only in HTML mode).
MSGID_ONVSCROLL | (string) Text - The text of the control. | Fired any time the scroll bar is moved (only in Text mode).
MSGID_ONVSCROLLBOTTOM | (string) Text - The text of the control. | Fired when the scroll bar reaches the bottom (only in Text mode).

Related Actions

The following actions are available for interacting with a scrolling text control:

DlgScrollingText.AppendLine

DlgScrollingText.GetProperties

DlgScrollingText.SetProperties


Select Package

Select Package Control

Overview

A select Package control is graphical tree structure that is used to represent different categories and packages that can be selected during the installation. This control contains two components, packages and another type of control called a category. A category is simply used to group a number of packages and/or other categories in the tree so that if a parent category is selected, all of the packages and categories within it will be selected as well. This control is mainly used on the Select Packages screen type. Examples of a select package control can be seen below:

Additional features of the select package control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

Note: Notification messages are not triggered when actions interact with this control.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by a select package control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them. For example, you can access the item "Type" from this table by using e_Details.Type.

e_MsgID

e_Details

Description

MSGID_ONSTATECHANGED

(number) Type - The Type of item that fired this. 0=Category, 1=Package.

(number) nCtrlID - The control ID of the category that fired this event. If a package fired it, 0 is returned.

(string) strCtrlID - The control ID of the package that fired this event. If a category fired it, "" is returned.

(number) State - The state of the item. See table below for state descriptions.

(number) Size - The size of the selected package (in KB). If a category is selected, 0 is returned.

(string) Description - The description text associated with the item.

(boolean) TotalSizeVisible - Whether or not the Show total size text is visible on the screen.

(boolean) Expanded - whether or not the category is expanded. Packages always return false.

Fired when the state of an item changes.

MSGID_ONSELCHANGED

same as above

Fired when the selection changes.

States

CONSTANT | VALUE | DESCRIPTION
CB_UNCHECKED | 1 | The checkbox is unchecked.
CB_CHECKED | 2 | The checkbox is checked.
CB_INDETERMINATE | 3 | The checkbox is in an indeterminate state. This means some of its children are selected and some are not.
CB_DIS_UNCHECKED | 4 | The checkbox is unchecked and disabled.
CB_DIS_CHECKED | 5 | The checkbox is checked and disabled.
CB_DIS_INDETERMINATE | 6 | The checkbox is in an indeterminate state and is disabled.

Related Actions

The following actions are available for interacting with a select package control:

DlgSelectPackages.GetCategoryProperties

DlgSelectPackages.SetCategoryProperties

DlgSelectPackages.UpdateDisplay


Static Text

Static Text Control

Overview

A static text control is used to display static text on a screen, such as the screen body text. An example of the Static Text control can be seen below:

Additional features of the static text control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Notification Messages

The static text control does not fire any notification messages.

Related Actions

The following actions are available for interacting with a static text control:

DlgStaticText.GetProperties

DlgStaticText.SetProperties


Timer

Timer Control

Overview

A timer control is a tool used to perform actions at a specified time interval. This control has no visual elements, and is controlled via actions.

Additional features of the timer control can be found in the following two categories:

  • Notification Messages

  • Related Actions

Note: A timer's CtrlID will always equal 0.

Notification Messages

A notification message is triggered whenever the user interacts with a control, or whenever user interaction affects a control in some way. Each notification message consists of a number that identifies the type of interaction that has occurred, and a table containing details specific to that type of interaction. These two values are passed to the screen's On Ctrl Message event as the event variables e_MsgID and e_Details.

(number) e_MsgID
A numeric constant that represents the specific notification message that was fired by the screen control. See the e_MsgID column below for all possible message ids that can be fired by a button control.

(table) e_Details
A table of additional details that may be passed by the control when certain notification messages are fired. See the e_Details column below for the kinds of details that are returned and the table indexes that you can use to access them.

e_MsgID | e_Details | Description
MSGID_ONTIMER | nil | Fired at the interval specified with Screen.StartTimer.

Related Actions

The following actions are available for interacting with a timer control:

Screen.StartTimer

Screen.StopTimer


Files - Overview

Files

Overview

While setups can be created to accomplish many different tasks, the installation of files is the main purpose of an installer. Setup Factory allows you to easily add, remove and edit the properties of files you want to install on the end users system.

Once you have determined what files you need to distribute in your install, you are ready to add them to your Setup Factory project.

Adding Files

Files can be added to your project using one of the following methods:

  • From the program menu by choosing Project > Add Files...

  • By pressing the Insert key on your keyboard to open the "Add Files to Project" dialog.

  • By right clicking on the design window and selecting Add Files...

  • By dragging the desired file(s) onto the Setup Factory design window.

Note: Adding a file to your project makes a reference to that file on your development system. It does not make a copy, or modify that file in any way.

Removing Files

Selected files can be removed from your project using one of the following methods:

  • From the program menu by choosing Project > Remove Selected.

  • By pressing the Delete key on your keyboard while a file is selected.

  • By right clicking on a selected file and choosing Remove.

Note: Removing a file from your project only removes its reference in your project. The file will not be deleted from your development system.

Editing File Properties

Once files have been added to your project, you may need to edit the properties of individual, or groups of files in your project file list.

There are two types of file properties dialogs in Setup Factory:

  • Single File Properties

  • Multiple File Properties

The dialog that opens depends upon how many files are selected for editing. You can edit the file properties for one or more files by first selecting them and then using one of the following methods:

  • For single files, you can double click them.

  • Choose Project > File Properties... from the program menu.

  • Right click on the selected file(s) and select File Properties...

  • By pressing Ctrl+Enter on your keyboard while the file(s) is selected.


Single File Properties - Overview

File Properties

Overview General Shortcuts Advanced Conditions Packages Notes

The File Properties dialog is where you can view and edit the properties of a file in your project. Some of the properties you can edit are the file's source and destination, registration, shortcut creation, install conditions and many more.

You can access the file properties dialog by selecting Project > File Properties... from the program menu while the file is selected.

Note: If you have more than one file selected when you select File Properties, the Multiple File Properties dialog is displayed instead.

The file properties dialog contains the following six tabs:

  • General

  • Shortcuts

  • Advanced

  • Conditions

  • Packages

  • Notes


Single File Properties - General

File Properties

Overview General Shortcuts Advanced Conditions Packages Notes

Source

Filename:

The name of the current file.

Details

Opens the Windows File Properties dialog that displays all of the properties of the current file. This includes information such as size, date and version information.

Local folder:

The location of the file on your development system. You can click the Browse button to select an alternate folder.

Tip: You can control what happens to the destination path when you change the source folder using the On File Source Change preference located in Edit > Preferences, Document > Files > Options.

Description:

A design-time description of the file. This description can be used by the developer to include further information about the particular file. The end user will not see this information.

Run-time folder:

The location of the file during the install, i.e. where the setup executable can find the file at run time.

Note: If the file is located on the Archive tab of the design environment, this field will be read-only containing the text "Archive."

Destination

Install to:

The directory that you want the file to be installed to on the user’s system. You can use any path-related session variable by itself, or in combination with a hard-coded path that you specify.

Note: Setup Factory will insert the correct directory here by default when you add the files to the project. Generally, you will not need to change the Install to setting.

Overwrite:

The action that will be taken if a file with the same name already exists in the location you want to install to. The relative newness of the file is determined by the version resource information built into the file. If the file does not contain version information, the file's date and time will be used as the criteria. Choose from:

Action | Description
Overwrite if existing file is same or older | If the file being installed is newer than or the same as the existing file, then overwrite the existing file.
Overwrite if existing file is older (Default) | If the file being installed is newer than the existing file, then overwrite the existing file.
Always overwrite existing file | The file being installed will always overwrite an existing file with the same name.
Never overwrite existing file | The file being installed will never overwrite an existing file with the same name.
Ask the user | The user will be asked whether or not the existing file should be overwritten.

Note: It is generally not a good idea to select "Always overwrite existing file" unless you are sure that is what you need to do. Also, do not select "Ask the user" unless you are sure that they have the knowledge to make such a decision. "Overwrite if existing file is older" is generally the safest and most conventional option for this situation.


Single File Properties - Shortcuts

File Properties

Overview General Shortcuts Advanced Conditions Packages Notes

Location

Desktop

Create a shortcut to this file on the user's Desktop.

Be prudent in your use of this option. It is generally not considered good etiquette to litter the user's desktop with shortcuts. At most, limit yourself to making a shortcut for only your main program, or use a screen to ask the users whether they want any desktop shortcuts created.

Startup

Create a shortcut to this file in the user's Startup folder.

Quick Launch

Create a shortcut to this file in the user's Quick Launch menu.

Note: Quick Launch shortcuts are part of Internet Explorer and are stored within each user's profile. Therefore quick launch shortcuts will only be created in the current user's profile regardless of the user profile chosen during the install.

Start menu

Create a shortcut to this file in the root of the user's Start menu.

Start menu > Programs

Create a shortcut to this file in the Start menu > Programs folder.

Start menu > AppFolder

Create a shortcut to this file in Start menu > Programs > %AppShortcutFolderName%. The session variable %AppShortcutFolderName% is expanded at run time to represent the folder that the user wants to add the shortcuts to.

Custom:

Create a shortcut to this file in a custom location. You can specify the folder on the user's system where you want to create the shortcut.

Start screen pinning (Windows 8):

Note: This setting is only available for Start menu shortcuts and only affects setups that are run on Windows 8 / Windows Server 2012 operating systems. As of Windows 8.1 and later, new application shortcuts are no longer pinned to the Windows Start Screen. Instead they're added to the Apps view. This decision by Microsoft was to let the user control what they want on their Start Screen given their preference instead of the decision being forced upon them by application developers.

This setting controls whether or not this shortcut will be pinned to the Windows 8 Start screen if it was created under the Start menu. Choose from the following options:

Default behavior

Use the default Windows behavior for this Start menu shortcut, based on the target file's type. In general all Start menu shortcuts that point to executables will be pinned to the Windows 8 Start screen by default.

Don't pin shortcut to start screen

Don't pin the Start menu shortcut to the Windows 8 Start screen. This allows you to remove any secondary pinned shortcuts.

Pin shortcut to start screen

Pin the Start menu shortcut to the Windows 8 Start screen. This option allows you to pin Start menu shortcuts that point to non-executables such as help files (however Microsoft discourages that).

Properties

Description:

The description that will accompany the shortcut(s). By default, if the file does not contain any version resources, the filename will be used as the description. If the file does contain version resources, its description will be extracted from that information. You may want to change this to something more meaningful and descriptive.

Comment:

An optional string to display in the "comment" section of the shortcut.

Start in folder:

The working directory for each of the shortcuts.

Command line arguments:

The command line arguments that you want passed to the file when the user uses the shortcut to launch the file.

Run mode:

The run mode for the file. Choose from:

Normal window

The file will be run with its window at normal size.

Minimized window

The file will be run with its window minimized.

Maximized window

The file will be run with its window maximized.

Shortcut key:

The shortcut key combination you want to assign to the shortcut. To assign a shortcut, place your cursor in this field and press the keyboard keys you want to use as the shortcut key. If this field contains the string "None", no shortcut key will be assigned.

Icon

Mode:

The icon you want to use for the shortcut. Choose from:

Default

Use the icon in the file's resources, or if the file does not have any icon resources, use the default Windows icon for its file type.

Custom

Use a custom icon file in the shortcut.

Icon path:

The path to the icon file that will be used to represent this shortcut on the user's system. The file must be a valid Windows icon (.ico) file. You can click the Browse button to open the Insert File Reference dialog where you can select an existing standard icon (.ico) file from your project, or add one. After the file has been selected, this field will contain the location to reference the icon file after it has been installed on the user's system.

Icon index:

The index of the icon you want to use for this shortcut. If there is only one icon in the file, or if you want to use the first icon found, enter 0.


Single File Properties - Advanced

File Properties

Overview General Shortcuts Advanced Conditions Packages Notes

Settings

Compress file

Compress the file when it's added to the setup executable. If unchecked, the file will not be compressed when it's added.

Turning off compression will decrease the time it takes to install the file, but will result in a larger setup. You may want to turn the compression off if you are distributing your setup on CD-ROM or over a Network where the size is not restricted or if the file is already compressed and you know that you will not be able to get much more compression out of it.

If your installer is being distributed on a very slow medium, such as Zip disks, it may actually be faster to leave compression on, because reading the extra data saved by compression would take more time than it does to decompress it.

Note: The Compress file option is not available for files on the External tab.

Suppress "In-Use" notice

Suppress a warning if the file is in use during installation and needs to be overwritten. If a file is in use, the built-in global variable _NeedsReboot will automatically be set to true to notify the setup that a reboot needs to take place.

If unchecked, a message will appear to warn the user if the file is in use and will ask them to shut down any running programs.

Use failsafe copy method

Extract the file to a temporary location, and then copy it to its final destination. This feature helps prevent the file from being corrupted if the install is aborted or if the user's system crashes midway through installing the file.

Note: This feature adds extra time to your installation, and will also increase the amount of temporary disk space required on the user's system during the installation. You should only use this feature for mission critical files, such as system files.

Create backup

Create a backup of the existing file (if present), before overwriting it during the installation. The existing file will be renamed to filename.bak. If filename.bak already exists, it will be named filename.bk1, or filename.bk2, etc. The new file will only be installed after the existing one has been backed up.

Tip: By default, each backed up file is created in the same directory as the target file. However there is a global variable called _BackupFolder that can be set as the backup directory for all files with this option enabled.

Note: Setup Factory does not restore backed up files during the uninstall, however the framework is available if you wish to perform this type of restoration. The full path and filename to each backed up file is stored with the information of the file being installed in the uninstall and can be accessed using the UninstallData.GetItem action.

Disable CRC check

Do not perform the usual CRC value integrity check on the file during installation. In general, you should not turn this option on. The CRC checking that is performed during setup is meant to ensure that your files are properly and completely installed and are not corrupted.

The only reason to turn this option on is if the file that you are installing will change from CD-ROM to CD-ROM and you do not want to re-build the setup each time the file changes. An example of such a file would be a customized data file that changes for each of your customers.

Attributes

This section allows you to specify the attributes of the file when it is installed on the user’s system. By default, the Use original option will be selected. This will ensure that the file's attributes will be the same on the user’s system as on yours.

Note: Changing the file attributes in this section does not affect the file on your development system. The attributes are only applied to the file when it's installed.

Use original

Preserve the attributes of the source file when the file is installed. If unchecked, you must specify the attributes for the installed file.

Read-only

Set the read-only file attribute when installed.

Archive

Set the archive file attribute when installed.

Hidden

Set the hidden file attribute when installed.

System

Set the system file attribute when installed.

Priority

Install order:

The order in which this file will be installed onto the user's system. Install order defaults to 1000. Files with lower install order values are installed first. This option is useful if certain files need to be installed and registered before others in your install archive.

Note: Archive files are always installed before External files in the install sequence. This install order value only applies to the files on the current tab.

Uninstall

Never remove

Do not remove this file during the uninstall process.

Shared/System file

Update the usage count for this file during installation and uninstallation. This feature should only be used for files that are shared by multiple programs, such as system files.

OLE/ActiveX

Register COM interfaces

Try to register this file if it is a COM Interface file. This will only work for controls that properly support the DLLRegisterServer interface. This option should properly register ActiveX controls (OCX) and other OLE inproc servers.

You can use the Test button located to the right of this checkbox to test the current file and see whether it supports DLLRegisterServer.

Tip: By default if the registration fails, an error dialog is shown (if the install is not running in silent mode). If an error occurs, the function g_OnRegisterFileFailed is called. If you would like to suppress this error message or change the way Setup Factory handles this situation, you can modify the function defined in the file _SUF70_Global_Functions.lua located in the Includes\Scripts folder of the main Setup Factory folder. The preferred method is to redefine the function in your project by copying and pasting it into the Resources > Global Functions and then making the desired modifications.

Register TypeLib

Try to register this file if it is a TypeLib file.

Font

Register as TrueType font

Try to automatically register and implement this file as a TrueType font during installation. This means that the font will be registered with the operating system and will be made available to the user. In order for this to work, the file must be a valid Windows .TTF file.

Font name:

The name that will be entered in the registry for the TrueType font.

You can click the Auto-Name button below this field to automatically scan the file and try to determine its embedded name. If the Auto-Name returns "Unknown" then the file is most likely not a valid Windows .TTF file.


Single File Properties - Conditions

File Properties

Overview General Shortcuts Advanced Conditions Packages Notes

The Conditions tab is used to conditionally include/exclude a file from the setup at build time or run time.

Build Configurations

The build configurations that will include the current file. You can check or uncheck the boxes in the build configurations tree. This feature can be used to prevent a file from being built into the setup.

Operating Systems

The operating systems that the file will be installed under. Some operating systems also allow you to select specific service release options. The main operating system categories are listed below:

  • Any OS (Selecting this option includes all OS's listed below)

  • Windows XP (SP2 or greater)

  • Windows Server 2003

  • Windows Vista

  • Windows Server 2008

  • Windows 7

  • Windows Server 2008 R2

  • Windows 8

  • Windows Server 2012

  • Windows 8.1

  • Windows Server 2012 R2

  • Windows 10

  • Windows Server 10

  • All Future OSs

Script Condition

A custom condition written in Lua script for the file. The script you enter must evaluate to a boolean value of true or false. At runtime this result will determine whether or not the file will be installed.

Some examples of valid conditions are:

my_variable > 10

This means if the numeric value of the variable "my_variable" is greater than 10, install the file. If the value is less than 10, do not install the file.

my_variable == "Custom"

This means if the string value of the variable "my_variable" equals the string "Custom", install the file. If the strings are not equal, do not install the file. For string comparisons, you must ensure that the contents of your variable, or constant is also enclosed in quotes. ie. "My Value" == "My Value" after variable expansion.


Single File Properties - Packages

File Properties

Overview General Shortcuts Advanced Conditions Packages Notes

Belongs to packages:

A list of all available packages. In order to add the current file to a package, simply check the box beside the package name. You can add the current file to as many packages as you like.

The file will not be installed unless one or more of the selected packages have been "selected" to be installed at runtime. A package is "selected" to be installed when its Install state is set to true.

Tip: You can get and set a package's install state using the SetupData.GetPackageProperties and SetupData.SetPackageProperties actions.

Select All

Include the current file in all current packages.

Deselect All

Exclude the current file from all current packages.


Single File Properties - Notes

File Properties

Overview General Shortcuts Advanced Conditions Packages Notes

Notes:

A private field used to store information about the current file. These notes are not included in the final build of the setup and are only available in the Setup Factory design environment.


Multiple File Properties - Overview

Multiple File Properties

Overview General Shortcuts Advanced Conditions Packages

The Multiple File Properties dialog is where you can view and edit the properties of multiple files in your project. Some of the properties you can edit for all of the selected files are their source and destination, registration, shortcut creation, install conditions and many more.

Many of the fields initially display the text "Use original values" which means that the current values for all of the selected files will not change unless you modify them.

You can access the multiple file properties dialog by first selecting a group of files in the file list and selecting Project > File Properties... from the program menu.

Note: If you have only one file selected when you select File Properties, the Single File Properties dialog is displayed instead.

The multiple file properties dialog contains the following five tabs:

  • General

  • Shortcuts

  • Advanced

  • Conditions

  • Packages


Multiple File Properties - General

Multiple File Properties

Overview General Shortcuts Advanced Conditions Packages

Source

Filename:

The edit state of the filename value for the selected files. You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the file name value for all selected files.

Note: The Details button is disabled when multiple files are selected.

Local folder:

The edit state of the location of the selected files on your development system. You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the local folder value for all selected files.

Tip: You can control what happens to the destination paths when you change the source folder using the On File Source Change preference located in Edit > Preferences, Document > Files > Options.

Description:

The edit state of the design-time description for the selected files. This description can be used by the developer to include further information about the particular file. The end user will not see this information.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the description for all selected files.

Run-time folder:

The edit state of the location of the selected files during the install, i.e. where the setup executable can find the files at run time.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the run-time folder value for all selected files.

Note: If the files are located on the Archive tab of the design environment, this field will be read-only containing the text "Archive".

Destination

Install to:

The edit state of the directory that you want the selected files to be installed to on the user’s system. You can use any path-related session variable by itself or in combination with a hard-coded path that you specify.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the install folder for all selected files.

Note: Setup Factory will insert the correct directory here by default when you add the files to the project. Generally, you will not need to change the Install to setting.

Overwrite:

The action that will be taken if a file with the same name already exists in the location you want to install to. The relative newness of the file is determined by the version resource information built into the file. If the file does not contain version information, the file's date and time will be used as the criteria. The options are:

Action | Description
<<Use original values>> | Use the original overwrite setting for each of the files. This is the setting for each file prior to opening the multiple file properties dialog.
Overwrite if existing file is same or older | If the file being installed is newer than or the same as the existing file, then overwrite the existing file.
Overwrite if existing file is older (Default) | If the file being installed is newer than the existing file, then overwrite the existing file.
Always overwrite existing file | The file being installed will always overwrite an existing file with the same name.
Never overwrite existing file | The file being installed will never overwrite an existing file with the same name.
Ask the user | The user will be asked whether or not the existing file should be overwritten.

Note: It is generally not a good idea to select "Always overwrite existing file" unless you are sure that is what you need to do. Also, do not select "Ask the user" unless you are sure that they have the knowledge to make such a decision. "Overwrite if existing file is older" is generally the safest and most conventional option for this situation.


Multiple File Properties - Shortcuts

Multiple File Properties

Overview General Shortcuts Advanced Conditions Packages

Location

Desktop

Create a shortcut to each selected file on the user's Desktop. Each shortcut's creation is based on the state of this tri-state check box.

Be prudent in your use of this option. It is generally not considered good etiquette to litter the user's desktop with shortcuts. At most, limit yourself to making a shortcut for only your main program, or use a screen to ask the users whether they want any desktop shortcuts created.

Startup

Create a shortcut to each selected file in the user's Startup folder. Each shortcut's creation is based on the state of this tri-state check box.

Quick launch

Create a shortcut to each selected file in the user's Quick Launch menu. Each shortcut's creation is based on the state of this tri-state check box.

Note: Quick Launch shortcuts are part of Internet Explorer and are stored within each user's profile. Therefore quick launch shortcuts will only be created in the current user's profile regardless of the user profile chosen during the install.

Start menu

Create a shortcut to each selected file in the root of the user's Start menu. Each shortcut's creation is based on the state of this tri-state check box.

Start menu > Programs

Create a shortcut to each selected file in the Start menu > Programs folder. Each shortcut's creation is based on the state of this tri-state check box.

Start menu > AppFolder

Create a shortcut to each selected file in Start menu > Programs > %AppShortcutFolderName%. The session variable %AppShortcutFolderName% is expanded at run time to represent the folder that the user wants to add the shortcuts to. Each shortcut's creation is based on the state of this tri-state check box.

Custom:

Create a shortcut to each selected file in a custom location. The edit state of the location (path to the folder) where you want to create the shortcut. Each shortcut's creation is based on the state of this tri-state check box.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the custom shortcut path for all selected files.

Start screen pinning (Windows 8):

Note: This setting is only available for Start menu shortcuts and only affects setups that are run on Windows 8 / Windows Server 2012. As of Windows 8.1 and later, new application shortcuts are no longer pinned to the Windows Start Screen. Instead they're added to the Apps view. This decision by Microsoft was to let the user control what they want on their Start Screen given their preference instead of the decision being forced upon them by application developers.

This setting controls whether or not each selected shortcut will be pinned to the Windows 8 Start screen if it was created under the Start menu. Choose from the following options:

<<Use original values>>

Use the original setting for each of the files. This is the setting for each file prior to opening the multiple file properties dialog.

Default behavior

Use the default Windows behavior for each file's Start menu shortcut, based on the target file's type. In general all Start menu shortcuts that point to executables will be pinned to the Windows 8 Start screen by default.

Don't pin shortcut to start screen

Don't pin each selected file's Start menu shortcut to the Windows 8 Start screen. This allows you to remove any secondary pinned shortcuts.

Pin shortcut to start screen

Pin each selected file's Start menu shortcut to the Windows 8 Start screen. This option allows you to pin Start menu shortcuts that point to non-executables such as help files (however Microsoft discourages that).

Properties

Description:

The state of the description that will accompany each shortcut. By default, Setup Factory uses the filename as the description. For example, if the current filename is EDITOR.EXE, the description will be EDITOR.EXE by default.

Note: The Description field is disabled when multiple files are selected.

Comment:

The state of the comment string that will accompany each shortcut.

Note: The Comment field is disabled when multiple files are selected.

Start in folder:

The edit state of the working directory for the shortcuts of the selected files.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the working directory for all selected files.

Command line arguments:

The edit state of the command line arguments that you want passed to each file when the user uses the shortcut to launch the file.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the command line arguments for all selected files.

Run mode:

The run mode for the selected shortcuts. Choose from:

<<Use original values>>

Use the original run mode for each of the files. This is the setting for each file prior to opening the multiple file properties dialog.

Normal

Each file will be run with its window at normal size.

Minimized

Each file will be run with its window minimized.

Maximized

Each file will be run with its window maximized.

Shortcut key:

The shortcut key combination for each file. This setting cannot be modified from this dialog. The original values will be used for each file. If you wish to modify this property for a file, you must use the Shortcuts tab on the Single File Properties dialog.


Multiple File Properties - Advanced

Multiple File Properties

Overview General Shortcuts Advanced Conditions Packages

Settings

Compress file

Compress all selected files when they are added to the setup executable. Each file's compression setting is based on the state of this tri-state check box.

Turning off compression will decrease the time it takes to install the file, but will result in a larger setup. You may want to turn the compression off if you are distributing your setup on CD-ROM or over a Network where the size is not restricted or if the file is already compressed and you know that you will not be able to get much more compression out of it.

If your installer is being distributed on a very slow medium, such as Zip disks, it may actually be faster to leave compression on, because reading the extra data saved by compression would take more time than it does to decompress it.

Note: The Compress file option is not available for files on the External tab.

Suppress "In-Use" notice

Suppress a warning if each file is in use during installation and needs to be overwritten. Each file's suppress setting is based on the state of this tri-state check box. If a file is in use, the built-in global variable _NeedsReboot will automatically be set to true to notify the setup that a reboot needs to take place.

If unchecked, a message will appear to warn the user if the file is in use and will ask them to shut down any running programs.

Use failsafe copy method

Extract each file to a temporary location, and then copy it to its final destination. This setting for each file is based on the state of this tri-state check box. This feature helps prevent the file from being corrupted if the install is aborted or if the user's system crashes midway through installing the file.

Note: This feature adds extra time to your installation, and will also increase the amount of temporary disk space required on the user's system during the installation. You should only use this feature for mission critical files, such as system files.

Create backup

Create a backup of the existing file (if present), before overwriting it during the installation for each of the selected files. This setting for each file is based on the state of this tri-state check box. The existing file will be renamed to filename.bak. If filename.bak already exists, it will be named filename.bk1, or filename.bk2, etc. The new file will only be installed after the existing one has been backed up.

Tip: By default, each backed up file is created in the same directory as the target file. However there is a global variable called _BackupFolder that can be set as the backup directory for all files with this option enabled.

Note: Setup Factory does not restore backed up files during the uninstall, however the framework is available if you wish to perform this type of restoration. The full path and filename to each backed up file is stored with the information of the file being installed in the uninstall and can be accessed using the UninstallData.GetItem action.

Disable CRC check

Do not perform the usual CRC value integrity check on each file during installation. This setting for each file is based on the state of this tri-state check box. In general, you should not turn this option on. The CRC checking that is performed during setup is meant to ensure that your files are properly and completely installed and are not corrupted.

The only reason to turn this option on is if the file that you are installing will change from CD-ROM to CD-ROM and you do not want to re-build the setup each time the file changes. An example of such a file would be a customized data file that changes for each of your customers.

Attributes

This section allows you to specify the attributes of the selected files when they're installed on the user’s system. By default, the Use original option will be selected. This will ensure that the file's attributes will be the same on the user’s system as on yours.

Note: Changing the file attributes in this section dos not affect the files on your development system. The attributes are only applied to the files when they're installed.

Use original

Preserve the attributes of the source file when the file is installed. If unchecked, you must specify the attributes for the installed file. This setting for each file is based on the state of this tri-state check box.

Read-only

Set the read-only file attributes for the selected files when installed. This setting for each file is based on the state of this tri-state check box.

Archive

Set the archive file attributes for the selected files when installed. This setting for each file is based on the state of this tri-state check box.

Hidden

Set the hidden file attributes for the selected files when installed. This setting for each file is based on the state of this tri-state check box.

System

Set the system file attributes for the selected files when installed. This setting for each file is based on the state of this tri-state check box.

Priority

Install order

The install order state in which the files are installed onto the user's system. Install order defaults to 1000. Files with lower install order values are installed first. This option is useful if certain files need to be installed and registered before others in your install archive.

You can click the edit button ( [image] ) to open the Edit Multiple Install Order Values dialog where you can edit this property for all selected files.

Note: Archive files are always installed before External files in the install sequence. This install order value only applies to the files on the current tab.

Uninstall

Never remove

Do not remove these files during the uninstall process. This setting for each file is based on the state of this tri-state check box.

Shared/System file

Update the usage count for all selected files during installation and uninstallation. This feature should only be used for files that are shared by multiple programs, such as system files. This setting for each file is based on the state of this tri-state check box.

OLE/ActiveX

Register COM interfaces

Try to register all selected files if they are COM Interface files. Each file's registration is based on the state of this tri-state check box. This will only work for controls that properly support the DLLRegisterServer interface. This option should properly register ActiveX controls (OCX) and other OLE inproc servers.

You can use the Test button to the right of this checkbox to test the current file and see whether it supports DLLRegisterServer.

Note: The Test button is not available when multiple files are selected.

Tip: By default if the registration fails, an error dialog is shown (if the install is not running in silent mode). If an error occurs, the function g_OnRegisterFileFailed is called. If you would like to suppress this error message or change the way Setup Factory handles this situation, you can modify this function defined in the file _SUF70_Global_Functions.lua located in the Includes\Scripts folder of the main Setup Factory 9 folder. The preferred method is to redefine the function in your project by copying and pasting it into the Resources > Global Functions and then making the desired modifications.

Register TypeLib

Try to register all selected files if they are TypeLib files. Each file's registration is based on the state of this tri-state check box.

Font

Register as TrueType font

Try to automatically register and implement all selected files as a TrueType fonts during installation. This means that the font will be registered with the operating system and will be made available to the user. In order for this to work, the file must be a valid Windows .TTF file. Each file's registration is based on the state of this tri-state check box.

Font name:

This field and the Auto-Name button are disabled when multiple files are selected.


Multiple File Properties - Conditions

Multiple File Properties

Overview General Shortcuts Advanced Conditions Packages

The Conditions tab is used to conditionally include/exclude the selected files from the setup at build time or run time.

Build Configurations

The build configurations that will include the selected files. You can check or uncheck the boxes in the build configurations tree. The inclusion of each file in each build configuration is based on the states of the quad-state check boxes.

Operating Systems

The operating systems that the selected files will be installed under. The operating system conditions for each file are based on the states of the quad-state check boxes. Some operating systems also allow you to select specific service release options. The main operating system categories are listed below:

  • Any OS (Selecting this option includes all OS's listed below)

  • Windows XP (SP2 or greater)

  • Windows Server 2003

  • Windows Vista

  • Windows Server 2008

  • Windows 7

  • Windows Server 2008 R2

  • Windows 8

  • Windows Server 2012

  • Windows 8.1

  • Windows Server 2012 R2

  • Windows 10

  • Windows Server 10

  • All Future OSs

Script Condition

The edit state of the custom condition written in Lua script, for the selected files. You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the script for all selected files.

The script you enter must evaluate to a boolean value of true or false. At runtime this result will determine whether or not the file will be installed.

Some examples of valid conditions are:

my_variable > 10

This means if the numeric value of the variable "my_variable" is greater than 10, install the file. If the value is less than 10, the file will not be installed.

my_variable == "Custom"

This means if the string value of the variable "my_variable" equals the string "Custom", install the file. If the strings are not equal, the file will not be installed. For string comparisons, you must ensure that the contents of your variable, or constant is also enclosed in quotes. ie. "My Value" == "My Value" after variable expansion.


Multiple File Properties - Packages

Multiple File Properties

Overview General Shortcuts Advanced Conditions Packages

Belongs to packages:

A list of all available packages and the inclusion state of the selected files. The inclusion of the selected files in each package is based on each package's tri-state check box. You can add the selected files to as many packages as you like.

These files will not be installed unless one or more of the selected packages has been "selected" to be installed. A package is "selected" to be installed when the package's Install property is equal to true.

Tip: You can get and set a package's install state using the SetupData.GetPackageProperties and SetupData.SetPackageProperties actions.

Select All

Include all of the currently selected files in all current packages. This will check all package's check boxes.

Deselect All

Exclude all of the currently selected files from all current packages. This will uncheck all package's check boxes.


Filters Manager - Overview

Filters Manager

Overview Filters

The filters manager allows you to add/remove and manage the global file filters in Setup Factory. When working with large amounts of files where subsets of them need to be customized, it's often convenient to only see the files whose properties require modifying, instead of the entire file list.

The filters manager allows you to define custom filters so you can control what files are visible in the Setup Factory file list. Once these filters have been defined, you can easily switch between filters to increase your work flow. These filters are saved on a global basis, so they can be used in all of your projects.

Tip: If you have a large number of files in your install, you can use the "Missing Files" filter to see all files that cannot be found at their defined source locations.

The filters manager contains one tab:

  • Filters


Filters

Filters Manager

Overview Filters

Name

The name of each currently defined filter.

Property

The zero-based index of the file property each filter is based upon.

Rule

The zero-based index of the rule that is applied to each filter.

Criteria

The criteria used for each of the current filters.

Add

Open the Filter Properties dialog where you can add a new filter to the global filter list.

Remove

Remove the selected filter from the global filter list.

Properties

Open the Filter Properties dialog where you can edit the properties of the currently selected filter.


Folder References - Overview

Folder References

Overview

During the development process it's not uncommon for files to change, or new files to be added to the setup periodically. When updating the installer, it is very easy to overlook new file entries that must be distributed. In cases where you do not need to set specific properties, creating a folder reference will keep your install up-to-date whenever you build.

Instead of adding individual files to your setup one by one, you can specify entire folders to include. This is accomplished by adding a folder reference to your setup whose contents are included at build time. You can include all the files and subfolders in the specified folder, or include/exclude files based on a file mask.

Note: Folder references will not include empty folders in your setup. Only folders that contain files that are included in the setup (based on the file mask), will be created by Setup Factory at runtime.

Adding Folder References

Folder references can be added to your project using one of the following methods:

  • From the program menu by choosing Project > Add Folder Reference...

  • By pressing Ctrl+Insert on your keyboard to open the "Browse For Folder" dialog.

  • By right clicking on the design window and selecting Add Folder Reference...

  • By dragging the desired folder onto the Setup Factory design window.

Note: Adding a folder reference to your project makes a reference to that folder's contents on your development system. It does not make a copy, or modify its contents in any way.

Removing Folder References

Selected folder references can be removed from your project using one of the following methods:

  • From the program menu by choosing Project > Remove Selected.

  • By pressing the Delete key on your keyboard while a folder reference is selected.

  • By right clicking on a selected folder reference and choosing Remove.

Note: Removing a folder reference from your project only removes its reference in your project. The folder or its contents will not be deleted from your development system.

Editing Folder Reference Properties

Once folder references have been added to your project, you may need to edit the properties of individual, or groups of folder references in your project file list.

There are two types of folder reference properties dialogs in Setup Factory:

  • Single Folder Reference Properties

  • Multiple Folder Reference Properties

The dialog that opens depends upon how many folder references are selected for editing. You can edit the properties for one or more folder references by first selecting them and then using one of the following methods:

  • For single folder references, you can double click them.

  • Choose Project > File Properties... from the program menu.

  • Right click on the selected folder reference(s) and select File Properties...

  • By pressing Ctrl+Enter on your keyboard while the folder reference(s) is selected.


Single Folder Reference Properties - Overview

Folder Reference Properties

Overview General Advanced Conditions Packages Notes

The Folder Reference Properties dialog is where you can view and edit the properties of a folder reference in your project.

You can access the folder reference properties dialog by selecting Edit > Properties... from the program menu while the folder reference is selected.

Note: If you have more than one folder reference selected when you select File Properties, the Multiple Folder Reference Properties dialog is displayed instead.

Note: Folder references will not include empty folders in your setup. Only folders that contain files that are included in the setup (based on the file mask), will be created by Setup Factory at runtime.

The folder reference properties dialog contains the following five tabs:

  • General

  • Advanced

  • Conditions

  • Packages

  • Notes


Single Folder Reference Properties - General

Folder Reference Properties

Overview General Advanced Conditions Packages Notes

Source

Local folder:

The location of the folder on your development system whose contents you want to include in the install. You can click the Browse button to select a alternate folder.

Recurse subfolders

Include the contents of all subfolders within the specified Local folder. This will also maintain the directory structure within the specified Local folder. If unchecked, only the files within the root of the folder will be included.

Note: Folder references will not include empty folders in your setup. Only folders that contain files that are included in the setup (based on the file mask), will be created by Setup Factory at runtime.

File mask:

The file mask you want to use to determine which files will be included or excluded from the setup at build time. You can use wildcards in this field. For example, *.* for all files, *.txt for all files with the .txt file extension etc.

Files that match

Only include files that match the specified file mask.

Files that do not match

Only include files that do not match the specified file mask.

Description:

A design-time description of the folder reference. This description can be used by the developer to include further information about the particular folder reference. The end user will not see this information.

Run-time folder:

The location of the folder's contents during the install, i.e. where the setup executable can find the contents at run time.

Note: If the folder reference is located on the Archive tab of the design environment, this field will be read-only containing the text "Archive".

Destination

Install to:

The location that you want the folder's contents to be installed to on the user’s system. You can use any path-related session variable by itself or with a hard-coded path that you specify.

Note: Setup Factory will insert the correct directory here by default when you add the files to the project. Generally, you will not need to change the Install to setting.

Overwrite:

The action that will be taken if a file with the same name already exists in the location you want to install to. The relative newness of the file is determined by the version resource information built into the file. If the file does not contain version information, the file's date and time will be used as the criteria. Choose from:

Action | Description
Overwrite if existing file is same or older | If the file being installed is newer than or the same as the existing file, then overwrite the existing file.
Overwrite if existing file is older (Default) | If the file being installed is newer than the existing file, then overwrite the existing file.
Always overwrite existing file | The file being installed will always overwrite an existing file with the same name.
Never overwrite existing file | The file being installed will never overwrite an existing file with the same name.
Ask the user | The user will be asked whether or not the existing file should be overwritten.

Note: It is generally not a good idea to select "Always overwrite existing file" unless you are sure that is what you need to do. Also, do not select "Ask the user" unless you are sure that they have the knowledge to make such a decision. "Overwrite if existing file is older" is generally the safest and most conventional option for this situation.


Single Folder Reference Properties - Advanced

Folder Reference Properties

Overview General Advanced Conditions Packages Notes

Settings

Compress files

Compress the files when they're added to the setup executable. If unchecked, the files will not be compressed when they're added.

Turning off compression will decrease the time it takes to install the files, but will result in a larger setup. You may want to turn the compression off if you are distributing your setup on CD-ROM or over a Network where the size is not restricted or if the files are already compressed and you know that you will not be able to get much more compression out of them.

If your installer is being distributed on a very slow medium, such as Zip disks, it may actually be faster to leave compression on, because reading the extra data saved by compression would take more time than it does to decompress it.

Note: The Compress files option is not available for folder references on the External tab.

Suppress "In-Use" notices

Suppress a warning if one of the files is in use during installation and needs to be overwritten. If a file is in use, the built-in global variable _NeedsReboot will automatically be set to true to notify the setup that a reboot needs to take place.

If unchecked, a message will appear to warn the user if the file is in use and will ask them to shut down any running programs.

Use failsafe copy method

Extract the files to a temporary location, and then copy them to their final destination. This feature helps prevent the files from being corrupted if the install is aborted or if the user's system crashes midway through installing the file.

Note: This feature adds extra time to your installation, and will also increase the amount of temporary disk space required on the user's system during the installation. You should only use this feature for mission critical files, such as system files.

Create backups

Create backups of the existing files (if present), before overwriting them during the installation. The existing files will be renamed to filename.bak. If filename.bak already exists, it will be named filename.bk1, or filename.bk2, etc. The new files will only be installed after the existing ones have been backed up.

Tip: By default, each backed up file is created in the same directory as the target file. However there is a global variable called _BackupFolder that can be set as the backup directory for all files with this option enabled.

Note: Setup Factory does not restore backed up files during the uninstall, however the framework is available if you wish to perform this type of restoration. The full path and filename to each backed up file is stored with the information of the file being installed in the uninstall and can be accessed using the UninstallData.GetItem action.

Disable CRC checks

Do not perform the usual CRC value integrity check on the files during installation. In general, you should not turn this option on. The CRC checking that is performed during setup is meant to ensure that your files are properly and completely installed and are not corrupted.

The only reason to turn this option on is if the file that you are installing will change from CD-ROM to CD-ROM and you do not want to re-build the setup each time the file changes. An example of such a file would be a customized data file that changes for each of your customers.

Attributes

This section allows you to specify the attributes of the files when they're installed on the user’s system. By default, the Use original option will be selected. This will ensure that each file's attributes will be the same on the user’s system as on yours.

Note: Changing the file attributes in this section does not affect the files on your development system. The attributes are only applied to the files when they're installed.

Use original

Preserve the attributes of the source files when the they're installed. If unchecked, you must specify the attributes for the installed files.

Read-only

Set the read-only file attribute when installed.

Archive

Set the archive file attribute when installed.

Hidden

Set the hidden file attribute when installed.

System

Set the system file attribute when installed.

Priority

Install order:

The order in which these files are installed onto the user's system. Install order defaults to 1000. Files with lower install order values are installed first. This option is useful if certain files need to be installed and registered before others in your install archive.

Note: Archive files are always installed before External files in the install sequence. This install order value only applies to the files on the current tab.

Uninstall

Never remove files

Do not remove these files during the uninstall process.

Shared/System files

Update the usage count for these files during installation and uninstallation. This feature should only be used for files that are shared by multiple programs, such as system files.

OLE/ActiveX

Register supported COM interfaces

Try to register the file if it is a COM Interface file. This will only work for controls that properly support the DLLRegisterServer interface. This option should properly register ActiveX controls (OCX) and other OLE inproc servers.

Tip: By default if the registration fails, an error dialog is shown (if the install is not running in silent mode). If an error occurs, the function g_OnRegisterFileFailed is called. If you would like to suppress this error message or change the way Setup Factory handles this situation, you can modify this function defined in the file _SUF70_Global_Functions.lua located in the Includes\Scripts folder of the main Setup Factory folder. The preferred method is to redefine the function in your project by copying and pasting it into the Resources > Global Functions and then making the desired modifications.

Register supported TypeLibs

Try to register the file if it's a TypeLib file.

Font

Register all TrueType fonts

Try to automatically register and implement all font files as TrueType fonts during installation. This means that the font will be registered with the operating system and will be made available to the user. In order for this to work, the file must be a valid Windows .TTF file.

Note: At build-time, Setup Factory will automatically try to get the font name from its resources. If the font name cannot be determined, this setting will be turned off for that particular file. In the case where the font name cannot be determined, the file must be added manually so you can specify the font name using the Single File Properties dialog.


Single Folder Reference Properties - Conditions

Folder Reference Properties

Overview General Advanced Conditions Packages Notes

The Conditions tab is used to conditionally include/exclude a folder reference from the setup at build time or run time.

Build Configurations

The build configurations that will include the current folder's contents. You can check or uncheck the boxes in the build configurations tree. This feature can be used to prevent a folder's contents from being built into the setup.

Operating Systems

The operating systems that the folder's contents will be installed under. Some operating systems also allow you to select specific service release options. The main operating system categories are listed below:

  • Any OS (Selecting this option includes all OS's listed below)

  • Windows XP (SP2 or greater)

  • Windows Server 2003

  • Windows Vista

  • Windows Server 2008

  • Windows 7

  • Windows Server 2008 R2

  • Windows 8

  • Windows Server 2012

  • Windows 8.1

  • Windows Server 2012 R2

  • Windows 10

  • Windows Server 10

  • All Future OSs

Script Condition

A custom condition written in Lua script for each file added by the folder reference. The script you enter must evaluate to a boolean value of true or false. At runtime this result will determine whether or not the files will be installed.

Some examples of valid conditions are:

my_variable > 10

This means if the numeric value of the variable "my_variable" is greater than 10, install the files. If the value is less than 10, the files will not be installed.

my_variable == "Custom"

This means if the string value of the variable "my_variable" equals the string "Custom", install the files. If the strings are not equal, the files will not be installed. For string comparisons, you must ensure that the contents of your variable, or constant is also enclosed in quotes. ie. "My Value" == "My Value" after variable expansion.


Single Folder Reference Properties - Packages

Folder Reference Properties

Overview General Advanced Conditions Packages Notes

Belongs to packages:

A list of all available packages. In order to add the folder reference's contents to a package, simply check the box beside the package name. You can add the folder reference to as many packages as you like.

The contents of the folder reference will not be installed unless one or more of the selected packages has been "selected" to be installed at run time. A package is "selected" to be installed when its install state is set to true.

Tip: You can get and set a package's install state using the SetupData.GetPackageProperties and SetupData.SetPackageProperties actions.

Select All

Include the folder reference in all current packages.

Deselect All

Exclude the folder reference from all current packages.


Single Folder Reference Properties - Notes

Folder Reference Properties

Overview General Advanced Conditions Packages Notes

Notes:

A private field used to store information about the current folder reference. These notes are not included in the final build of the setup and are only available in the Setup Factory design environment.


Multiple Folder Reference Properties - Overview

Multiple Folder Reference Properties

Overview General Advanced Conditions Packages

The Multiple Folder Reference Properties dialog is where you can view and edit the properties of multiple folders in your project. Some of the properties you can edit for all of the selected folders are their source and destination, attributes, install conditions and many more.

Many of the fields initially display the text "Use original values" which means that the current values for all of the selected folder references will not change unless you modify them.

You can access the multiple folder references properties dialog by first selecting a group of folder references in the file list and selecting Project > File Properties... from the program menu.

Note: If you have only one folder reference selected when you select the folder reference properties, the Single Folder Properties dialog is displayed instead.

Note: Folder references will not include empty folders in your setup. Only folders that contain files that are included in the setup (based on the file mask), will be created by Setup Factory at runtime.

The multiple file properties dialog contains the following four tabs:

  • General

  • Advanced

  • Conditions

  • Packages


Multiple Folder Reference Properties - General

Multiple Folder Reference Properties

Overview General Advanced Conditions Packages

Source

Local folder:

The edit state of the location of the folders on your development system whose contents you want to include in the install. You can click the Browse button to select a different folder or click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the folder name for all selected folder references.

Recurse subfolders

Include all subfolders within the all selected Local folders. If unchecked, only the files within the root of the folders will be included. The recursion of the subfolders for each folder reference is based on the state of this tri-state check box.

Note: Folder references will not include empty folders in your setup. Only folders that contain files that are included in the setup (based on the file mask), will be created by Setup Factory at runtime.

File mask:

The file mask state that will be used to determine which files will be included or excluded from the setup at build time. You can use wildcards in this field. For example, *.* for all files, *.txt for all files with the .txt file extension etc.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the file mask for all selected folder references.

Files that match

Only include files that match the specified file mask for all selected folder references.

Files that do not match

Exclude any files that match the specified file mask for all selected folder references.

<<Don't change>>

Don't change the file mask for any of the selected folder references.

Description:

The edit state of the design-time description for the selected folder references. This description can be used by the developer to include further information about the particular folder. The end user will not see this information.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the description for all selected folder references.

Run-time folder:

The edit state of the location of each folder during the install, i.e. where the setup executable can find the folder at run time.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the run-time folder for all selected folder references.

Note: If the folder reference is located on the Archive tab of the design environment, this field will be read-only containing the text "Archive".

Destination

Install to:

The edit state of the location that you want each folder and its contents to be installed to on the user’s system. You can use any path-related session variable by itself or with a hard-coded path that you specify.

You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the destination for all selected folder references.

Note: Setup Factory will insert the correct directory here by default when you add the folder reference to the project. Generally, you will not need to change the Install to setting.

Overwrite:

The action that will be taken if a file with the same name already exists in the location you want to install to. The relative newness of the file is determined by the version resource information built into the file. If the file does not contain version information, the file's date and time will be used as the criteria. The options are:

Action | Description
<<Use original values>> | Use the original overwrite setting for each of the folder reference's files. This is the setting for each folder reference prior to opening the multiple folder reference properties dialog.
Overwrite if existing file is same or older | If the file being installed is newer than or the same as the existing file, then overwrite the existing file.
Overwrite if existing file is older (Default) | If the file being installed is newer than the existing file, then overwrite the existing file.
Always overwrite existing file | The file being installed will always overwrite an existing file with the same name.
Never overwrite existing file | The file being installed will never overwrite an existing file with the same name.
Ask the user | The user will be asked whether or not the existing file should be overwritten.

Note: It is generally not a good idea to select "Always overwrite existing file" unless you are sure that is what you need to do. Also, do not select "Ask the user" unless you are sure that they have the knowledge to make such a decision. "Overwrite if existing file is older" is generally the safest and most conventional option for this situation.


Multiple Folder Reference Properties - Advanced

Multiple Folder Reference Properties

Overview General Advanced Conditions Packages

Settings

Compress files

Compress all files within the selected folder references when they are added to the setup executable. Each folder reference's compression setting is based on the state of this tri-state check box.

Turning off compression will decrease the time it takes to install the files, but will result in a larger setup. You may want to turn the compression off if you are distributing your setup on CD-ROM or over a Network where the size is not restricted or if the files are already compressed and you know that you will not be able to get much more compression out of them.

If your installer is being distributed on a very slow medium, such as Zip disks, it may actually be faster to leave compression on, because reading the extra data saved by compression would take more time than it does to decompress it.

Note: The Compress files option is not available for folder references on the External tab.

Suppress "In-Use" notices

Suppress a warning if each file of the folder reference is in use during installation and needs to be overwritten. Each folder reference's suppress setting is based on the state of this tri-state check box. If a file is in use, the built-in global variable _NeedsReboot will automatically be set to true to notify the setup that a reboot needs to take place.

If unchecked, a message will appear to warn the user if the file is in use and will ask them to shut down any running programs.

Use failsafe copy method

Extract each file to a temporary location, and then copy it to its final destination. This setting for each folder reference is based on the state of this tri-state check box. This feature helps prevent the file from being corrupted if the install is aborted or if the user's system crashes midway through installing the file.

Note: This feature adds extra time to your installation, and will also increase the amount of temporary disk space required on the user's system during the installation. You should only use this feature for mission critical files, such as system files.

Create backups

Create a backup of the existing file (if present), before overwriting it during the installation for each file of the selected folder references. This setting for each folder reference is based on the state of this tri-state check box. The existing file will be renamed to filename.bak. If filename.bak already exists, it will be named filename.bk1, or filename.bk2, etc. The new file will only be installed after the existing one has been backed up.

Tip: By default, each backed up file is created in the same directory as the target file. However there is a global variable called _BackupFolder that can be set as the backup directory for all files with this option enabled.

Note: Setup Factory does not restore backed up files during the uninstall, however the framework is available if you wish to perform this type of restoration. The full path and filename to each backed up file is stored with the information of the file being installed in the uninstall and can be accessed using the UninstallData.GetItem action.

Disable CRC checks

Do not perform the usual CRC value integrity check on each file of the folder reference during installation. This setting for each folder reference is based on the state of this tri-state check box. In general, you should not turn this option on. The CRC checking that is performed during setup is meant to ensure that your files are properly and completely installed and are not corrupted.

The only reason to turn this option on is if the file that you are installing will change from CD-ROM to CD-ROM and you do not want to re-build the setup each time the file changes. An example of such a file would be a customized data file that changes for each of your customers.

Attributes

This section allows you to specify the attributes of the files of the selected folder references when they're installed on the user’s system. By default, the Use original option will be selected. This will ensure that the file's attributes will be the same on the user’s system as on yours.

Note: Changing the file attributes in this section dos not affect the files on your development system. The attributes are only applied to the files when their installed.

Use original

Preserve the attributes of the source file when the folder reference file is installed. If unchecked, you must specify the attributes for the installed file. This setting for each folder reference is based on the state of this tri-state check box.

Read-only

Set the read-only file attributes for the files of the selected folder references when installed. This setting for each folder reference is based on the state of this tri-state check box.

Archive

Set the archive file attributes for the files of the selected folder references when installed. This setting for each folder reference is based on the state of this tri-state check box.

Hidden

Set the hidden file attributes for the files of the selected folder references when installed. This setting for each folder reference is based on the state of this tri-state check box.

System

Set the system file attributes for the files of the selected folder references when installed. This setting for each folder reference is based on the state of this tri-state check box.

Priority

Install order:

The order in which files are installed onto the user's system. Install order defaults to 1000. Files with lower install order values are installed first. This option is useful if certain files need to be installed and registered before others in your install archive.

The install order state in which the folder reference's contents are installed onto the user's system. Install order defaults to 1000. Folder references with lower install order values are installed first. This option is useful if certain files need to be installed and registered before others in your install archive.

You can click the edit button ( [image] ) to open the Edit Multiple Install Order Values dialog where you can edit this property for all selected folder references.

Note: Archive files are always installed before External files in the install sequence. This install order value only applies to the files on the current tab.

Uninstall

Never remove files

Do not remove the folder reference's files during the uninstall process. This setting for each folder reference is based on the state of this tri-state check box.

Shared/System files

Update the usage count for files within all selected folder references during installation and uninstallation. This feature should only be used for files that are shared by multiple programs, such as system files. This setting for each folder reference is based on the state of this tri-state check box.

OLE/ActiveX

Register supported COM interfaces

Try to register all files within the selected folder references if they are COM Interface files. Each folder reference's registration setting is based on the state of this tri-state check box. This will only work for controls that properly support the DLLRegisterServer interface. This option should properly register ActiveX controls (OCX) and other OLE inproc servers.

Tip: By default if the registration fails, an error dialog is shown (if the install is not running in silent mode). If an error occurs, the function g_OnRegisterFileFailed is called. If you would like to suppress this error message or change the way Setup Factory handles this situation, you can modify this function defined in the file _SUF70_Global_Functions.lua located in the Includes\Scripts folder of the main Setup Factory 9 folder. The preferred method is to redefine the function in your project by copying and pasting it into the Resources > Global Functions and then making the desired modifications.

Register supported TypeLibs

Try to register all files with the selected folder references if they are TypeLib files. Each folder reference's file registration is based on the state of this tri-state check box.

Font

Register all TrueType fonts

Try to automatically register and implement all files in the selected folder references as a TrueType fonts during installation. This means that the font will be registered with the operating system and will be made available to the user. In order for this to work, the file must be a valid Windows .TTF file. Each folder reference's registration setting is based on the state of this tri-state check box.

Note: At build-time, Setup Factory will automatically try to get the font name from its resources. If the font name cannot be determined, this setting will be turned off for that particular file. In the case where the font name cannot be determined, the file must be added manually so you can specify the font name using through the Single File Properties dialog.


Multiple Folder Reference Properties - Conditions

Multiple Folder Reference Properties

Overview General Advanced Conditions Packages

The Conditions tab is used to conditionally include/exclude the selected folder references from the setup at build time or run time.

Build Configurations

The build configurations that will include the selected folder references. You can check or uncheck the boxes in the build configurations tree. The inclusion of each folder reference in each build configuration is based on the states of the quad-state check boxes.

Operating Systems

The operating systems that the selected folder references will be installed under. The operating system conditions for each folder reference are based on the states of the quad-state check boxes. Some operating systems also allow you to select specific service release options. The main operating system categories are listed below:

  • Any OS (Selecting this option includes all OS's listed below)

  • Windows XP (SP2 or greater)

  • Windows Server 2003

  • Windows Vista

  • Windows Server 2008

  • Windows 7

  • Windows Server 2008 R2

  • Windows 8

  • Windows Server 2012

  • Windows 8.1

  • Windows Server 2012 R2

  • Windows 10

  • Windows Server 10

  • All Future OSs

Script Condition

The edit state of the custom condition written in Lua script for the selected folder references. You can click the edit button ( [image] ) to open the Edit Multiple Values dialog where you can change the script for all selected folder references.

The script you enter must evaluate to a boolean value of true or false. At runtime this result will determine whether or not the file within the folder reference will be installed.

Some examples of valid conditions are:

my_variable > 10

This means if the numeric value of the variable "my_variable" is greater than 10, install the file. If the value is less than 10, the file will not be installed.

my_variable == "Custom"

This means if the string value of the variable "my_variable" equals the string "Custom", install the file. If the strings are not equal, the file will not be installed. For string comparisons, you must ensure that the contents of your variable, or constant is also enclosed in quotes. ie. "My Value" == "My Value" after variable expansion.


Multiple Folder Reference Properties - Packages

Multiple Folder Reference Properties

Overview General Advanced Conditions Packages

Belongs to packages:

A list of all available packages and the inclusion state of the selected folder references. The inclusion of the selected folder references in each package is based on each package's tri-state check box. You can add the selected folder references to as many packages as you like.

The files within these folder references will not be installed unless one or more of the selected packages has been "selected" to be installed. A package is "selected" to be installed when the package's Install property is equal to true.

Tip: You can get and set a package's install state using the SetupData.GetPackageProperties and SetupData.SetPackageProperties actions.

Select All

Include all of the currently selected folder references in all current packages. This will check all package's check boxes.

Deselect All

Exclude all of the currently selected folder references from all current packages. This will uncheck all package's check boxes.


Overview

Languages

Overview Settings

Many developers distribute their applications to locations around the world whose native languages differ. For this reason, it is often desired to present the install's instructions in different languages based upon the language currently defined in their Operating System's Regional Settings.

Setup Factory has the ability to automatically detect the user's system language and also display messages and screens in that language. The developer has full control over what languages are supported in their setup and what they would like to present to the user in those cases.

Language text is mainly used for messages generated throughout the install, and on screens, both of which can be easily translated by the developer for multi-lingual installs.

All of the language files are in XML format for easy editing in an XML or text editor. The available language files can be found in ...\Setup Factory 9\Languages.

Screens can also be easily translated on a screen-by-screen basis, based on the languages that are currently supported by the setup. Those translations can be done on the screen itself for each supported language, or externally by a translator. You can select the language being translated for each screen on the Settings tab of its properties dialog.

To access the Languages dialog, choose Project > Languages... from the program menu.

The languages dialog contains one tab:

  • Settings


Settings

Languages

Overview Settings

The Languages tab is used to display the languages currently supported by your setup. When a language is supported, this means that if that language is detected, it will use the associated message file and use that language's screen translations if applicable. The language message files are stored in XML (.xml) for easy editing and creation.

Languages supported by setup:

A list of all of the languages that are currently supported by the Setup Factory project.

Language

The names of the languages currently added to the setup.

Default

Whether or not the language is the default language for this project. This is set to TRUE if the language is the default language, and blank if it is not. If the user's detected language is not present in the supported language list, the setup will use this language for its messages and screens.

Note: There can only be one default language per setup.

Language File

The full path to the XML language message files. You will find the available language files in the "Languages" subfolder of the main Setup Factory directory.

Note: If a language is added that currently does not have an available message file, "[Same as Default Language]" will appear. In the case where there is no pre-made message file for that language, the "Default" message file will be used. You can create and translate your own message files if a pre-made file is not available.

Add

Opens the Add New Language dialog where you can add a new language to be supported by your setup.

Remove

Removes the currently selected language from your setup.

Note: You cannot remove the default language. If you wish to remove that particular language, first set a different language to be the default language for the setup.

Set Default

Set the currently selected language to be the "Default" language. This means that if the detected language is not supported by your setup, or if one of the supported languages does not have a message file associated with it, this language's message file will be used.

Import

Browse your system for an XML language message file.

More Languages

Opens your default web browser to a web site where you can download additional language modules to use in your projects.


Packages - Overview

Packages

Overview Settings

Packages are special categories that you can define in order to group related files together. They're often used to present optional components and letting users choose which parts of an application they want to install on their system.

You can have as many packages in a Setup Factory project as you want. Each package has an ID, display name and an optional description that you can use to provide information about the package to your users. This information will appear on the Select Packages screen that you can include in your installer. The Select Packages screen allow your users to select which packages they want to install.

Each file in a Setup Factory project can be assigned to one or more packages. When a file is assigned to a package, it will only be installed if the user selects that package at run time. In other words, when users choose a package, they automatically enable the installation of all the files that belong to it.

To access the Packages dialog, choose Project > Packages... from the program menu.


Settings

Packages

Overview Settings

Packages:

A tree view list of packages currently added to the install.

Show files

Show all files that are currently a part of each package. Each file reference will look something like "(Archive) %AppFolder%\MyFile.txt". If unchecked, all file information will be hidden.

Show infotips

Show quick reference tooltips in the packages list. These tooltips display immediate information when you mouse over contents in the packages list. The tooltip for files include the filename, source path and destination path. The tooltip for packages include the majority of the packages' properties.

Add

Opens the Package Properties dialog where you can create a new package.

Remove

Removes the currently selected package from your setup.

Edit

Opens the Package Properties dialog where you can edit the properties of the currently selected package.

Duplicate

Creates a duplicate copy of the selected package, renaming it with the prefix "Copy of..."

Advanced

Export Language

Expands to a menu containing all languages in the project available for exporting the package strings. Clicking on a language will open a Save As dialog so you can choose the path that the selected language will be exported to. A dialog message will notify you of success or failure.

Import Language...

Open a file browse dialog so you can select a package's language XML file that you want to import into the currently selected package. A dialog message will notify you of success or failure.


Preferences - Overview

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

The Preferences dialog is where you can find the settings and options that let you configure the Setup Factory design environment to your liking.

To access the Preferences dialog, choose Edit > Preferences... from the program menu.

The following categories are on the Preferences dialog:

  • Build

  • Code Signing

  • Document

  • Files

    • Options

  • Drop

  • Languages

  • Environment

  • Folders

  • Script Editor

  • Spell Checker

  • Startup

  • Updates


Build Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

You can use these settings to control how Setup Factory builds a project. To view and change any build options, use the Build Settings dialog (Publish > Settings...).

Build with Publish Wizard

If selected, Setup Factory will use the Publish Wizard when building. If not selected, Setup Factory will build using the settings specified in Build Settings.

Open output folder after build

Make Setup Factory open the output folder by default after a build has completed.

Confirm before building (non-Wizard mode only)

If selected, Setup Factory will confirm the build process before continuing. If unselected, Setup Factory will build the project as soon as build is selected.

Note: This setting has no effect when the Publish Wizard is used.

Report status during build

Whether to output progress information during the build of the setup. Unchecking this option decreases the build time of the setup.

UPX compress runtime

This setting controls whether or not 32-bit non-skinned runtimes will be UPX compressed.

Exclude fonts from build:

The font face names that will not be included in the build if you choose to override the default fonts in a theme or on a page. By default this field includes Arial, Courier New, and Times New Roman. This saves you from the space taken up by say Arial when all you did was change the font size.


Code Signing Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Code Signing Defaults

These settings are the default values that will be used on the Code Signing tab of the Build Settings dialog when new projects are started.

Code sign setups

Code sign all new setups/uninstalls during the build process. See Authenticode Code Signing for more information.

Code signing tool:

The tool you want to use to digitally sign all new project setups. Choose from:

SignTool.exe

Use SignTool.exe to digitally sign the setup file. This tool could not be distributed, but is available in the \Bin folder of the Platform Software Development Kit (SDK). For more information, see MSDN: SignTool (Windows).

SignCode.exe

Use SignCode.exe to digitally sign the setup file. This tool could not be distributed, and only ships with the .NET Framework SDK version 1.0 and 1.1. For more information, see MSDN: File Signing Tool (Signcode.exe).

Tool location:

The full path and filename of the chosen code signing tool on your system (SignTool.exe or SignCode.exe). You can click the Browse button to select the file.

Certificate filename:

The full path and filename of the certificate to use for signing all new project setups. If SignTool.exe is selected, this file must be a "Personal Information Exchange" file (*.PFX). If SignCode.exe is selected, this file must be a "Software Publisher Certificate" file (*.SPC). You can click the Browse button to select the file.

Tip: If your .PFX file is password protected, you must pass its value in the Other arguments field using the /p option. For example: /p "mypassword". For more information, see MSDN: SignTool (Windows).

Private key filename:

The full path and filename of the "Private Key" file (*.pvk) to use for signing all new project setups. This file is only used when SignCode.exe is the selected tool. You can click the Browse button to select the file.

Timestamp URL:

The URL of a timestamp DLL on the Web to use for all new setups, such as: http://timestamp.verisign.com/scripts/timstamp.dll. If you do not want to timestamp the setup file, leave this field blank.

Other arguments:

Any additional options you would like to pass to the code signing tool. If you leave any of the code signing fields blank (except for tool location), you can pass their values as command line options. Setup Factory automatically passes the "sign" argument when "SignTool.exe" is the selected tool.


Document Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Auto-Save

Enabled

Make Setup Factory save your project automatically at regular intervals.

Interval:

The time in minutes to wait between autosaves. This is how long Setup Factory will wait after it automatically saves your project, before it automatically saves the project again.

Purge Level:

The maximum number of autosaved project files that you want Setup Factory to keep at any given time.

The files will be saved at regular intervals in a subfolder called "Autosave" located in the same directory as your project file. The files will automatically be named according to the following format:

autosave_YYYY-MM-DD_HH-MM-SS.sf8

Undo/Redo

Levels

The maximum number of changes that will be undo-able in Setup Factory. (Set this to 0 to disable the undo/redo feature.)

Note: You can change how added files are handled by changing the Files Preferences. The default languages included in projects are specified in the Languages Preferences.

New Projects

Start with Project Wizard

The project wizard will be used whenever a new project is created.

Start with empty project

A blank project will be used whenever a new project is created.


Files Preferences

Preferences

Document Files Options

File Properties

Create shortcuts for files with extensions:

A semi-colon delimited list of the extensions that Setup Factory will create shortcuts for by default.

Register all TrueType .TTF files

If checked, all TrueType .TTF files will be automatically registered with the user's system when installed.

Scan .DLL/.OCX for DllRegisterServer

If checked, all .DLL and .OCX files will be scanned for DllRegisterServer when added to the project.

Do not scan the following filenames:

A semi-colon delimited list of filenames that should not be scanned for DLLRegisterServer support. Filenames are not case-sensitive.

Scan Version Information

File extensions:

A list of the extensions of the file types that you want to scan for version information every time a file is added to the project, or the project's file lists are refreshed.

Project File (Restart Required for Changes to Take Effect)

Tip: The settings below are useful for Setup Factory project files that are under source control.

Save time and statistical information for each file

Whether or not to save file date/time information, file size and file attributes for each file in your project.

Save version information for each file

Whether or not to save file version information for each file in your project.


Options Preferences

Preferences

Document Files Options

On File Source Change

The following options control what happens when you change a file's source path using the browse button on the File Properties or Multiple File Properties dialogs.

Update destination

Update the destination path to match the new source location.

Leave destination the same

Don't change the existing destination path.

Ask

Show a dialog that asks me.


Drop Preferences

Preferences

Document Drop

On Drop Folder(s)

Add folder reference

If selected, any folders inserted into a Setup Factory project by dragging and dropping will be automatically inserted as folder references.

Add file reference

If selected, any folders inserted into a Setup Factory project by dragging and dropping will be automatically inserted as file references.

Ask

If selected, when any folders are inserted into a Setup Factory project by dragging and dropping, a dialog will be displayed asking if the folders should be added as folder references, or as file references.


Languages Preferences

Preferences

Document Languages

Default Languages to add to new projects:

A list of languages that will be added to any new projects created.

Language

The display name of the language selected.

Default

Whether the selected language will be the default language for new projects created.

Add

Opens the add new language dialog.

Remove

Removes the selected language.

Set Default

Sets the selected language as the default language.


Environment Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Colors

Missing files

Files listed in Setup Factory that cannot be found at the location referenced will be shown in this color.

Themes

GUI

The default style to use for the Graphical User Interface.

Docking pane

The default style to use for the docking pane.

Task pane

The default style to use for the task pane.

Animation

Whether menu animation in Setup Factory is on or off.

Note: The default folders used by Setup Factory are specified in the Folder Preferences dialog.


Folder Preferences

Preferences

Environment Folders

Temporary build files:

The full path to the folder where Setup Factory will store any temporary build files that it needs to generate during the build process. (Set to your Temp folder by default.) Click the browse button to select a new folder.

Default output folder:

The full path to the folder where Setup Factory will store the file(s) generated during the build process.

Preference files:

The full path to the location where Setup Factory will store its preferences files.

Project files:

The full path to the default location where Setup Factory will store any project files which are saved.

Additional themes:

A list of folder paths that you want Setup Factory to parse looking for additional project themes beyond the ones in the Themes folder of the program. For example, C:\MyProjectThemes and Z:\SUFThemes. This allows you to store themes on a network drive that can be shared between products and developers. You can use the New, Delete and Up/Down arrows to manipulate the folder list.

If Setup Factory encounters a theme with a name that already exists when reading in the available themes, it will use the last read theme. For example, if a custom theme in a different directory has the same name as a theme located in the product themes folder, the custom theme will override the one in the themes folder.

To store a theme in a different location, first save it to the program's Themes folder and then copy the created theme folder to an external location.


Script Editor Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Double-click opens action's properties dialog

Controls whether or not the action's properties dialog will open when you double-click an action in the script editor window. If unchecked, double-clicking any text in the script editor simply selects the text, as in most other text editors.

Automatic syntax checking

Controls whether or not a check is performed on scripts to make sure they are syntactically correct. It does not check for logical or other programming errors, simply syntax. This check is performed when leaving the current script editor window. If unchecked, no syntax checking is performed.

Confirm cancel when scripts are modified

Controls whether or not a confirmation dialog will appear after you click the Cancel button in the action editor when there are unsaved changes. If unchecked, cancelling will exit the dialog without notice and you will lose any changes that have been made.


Spell Checker Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

You can use these settings to control the spell checker features within fields that support spell checking (each field that supports spell checking will enable a Spell Checking... option in the right-click context menu).

Always suggest corrections

Suggest possible corrections for any spelling mistakes encountered.

Suggest from main dictionaries only

Show spelling mistake suggestions from the Main Dictionaries only (not the Custom Dictionary).

Ignore words in UPPERCASE

Ignore any uppercase words in the text. For example, INDIGO ROSE.

Ignore words with numbers

Ignore any words in the text that contain numbers. For example, am4.

Ignore Internet and file addresses

Ignore any internet or file addresses in the text. For example, http://www.indigorose.com, or C:\Program Files\myfile.txt.

Capitalize sentences

Automatically capitalize the first letter of a new sentence.

Custom Dictionary:

The full path to your custom dictionary file. This file can be included or added to when you encounter common words that are not in the main dictionary. You can click the browse button to select a custom dictionary file (*.dic). Additional dictionaries can be downloaded from Indigo Rose's web site, www.indigorose.com.

Main Dictionaries:

The full paths to your main dictionary files (*.lex). You can use the New, Delete and Up/Down arrows to manipulate the dictionary file list.


Startup Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

When this Program Starts

Show welcome dialog

Shows the welcome dialog, allowing a choice of creating a new project or opening an existing project.

Open last project

Automatically opens the last project used when Setup Factory is launched.

Start new project

Automatically starts a new project when Setup Factory is launched.


Updates Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Auto-Update

Enabled

Whether to automatically check for new versions of the Setup Factory program according to the settings below. If you disable this feature, make sure that you choose the Check for Update item from the Help menu from time to time to ensure that you are always using the most current release of Setup Factory.

Frequency:

How often (the number of days) you want Setup Factory to check for an update.

Hide interface

Whether to hide the update interface when the program checks for an update.

Connection...

Open the Internet Properties dialog to the Connections tab where you can configure the connection settings that Setup Factory will use when it checks for updates.


Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

Most of the features of Setup Factory can be accessed from the program menus. By default, the program menus are located at the top of the Setup Factory program window just under the title bar.

The program menus are organized into nine categories:

  • File

  • Edit

  • Project

  • Resources

  • Uninstall

  • Publish

  • View

  • Tools

  • Help


File Menu

Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

New Project

Opens a new Setup Factory project. If there are any unsaved changes in the current project, you will be prompted to save them. You can also access this menu item using Ctrl+N.

Open...

Opens a previously saved Setup Factory project file. Setup Factory 9 projects have the ".suf" file extension. You can access this menu item using Ctrl+O. You can also open version 6.0, version 7.0 and version 8.0 project files using the "Files of type" drop down.

Note: When opening a project file created with a previous version, Setup Factory 9 will analyze your project and may create a report detailing where minor changes may need to be made for compatibility. See Changes to Setup Factory for more information.

Save

Saves the current project file. You can also access this menu item using Ctrl+S.

Save As...

Saves the current project under a different name.

Properties...

Opens the Project File Properties dialog where you can add project specific developer notes.

Recent File

This is a list of the most recently viewed Setup Factory projects.

Exit

Closes the current project and exits out of Setup Factory. If there are any unsaved changes in the current project, you will be prompted to save them.


Edit Menu

Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

Undo

Undoes the last command performed in the program. You can also access this menu item using Ctrl+Z.

Redo

Redoes the last Undo command performed in the program. You can also access this menu item using Ctrl+Y.

Cut

Removes the currently selected files or folder references from the project and stores them in the Windows clipboard. Once on the clipboard, they can be pasted to another file tab (Archive or External) or another project. You can also access this menu item using Ctrl+X.

Copy

Copies the currently selected files or folder references to the Windows clipboard. Once on the clipboard, they can be pasted to another file tab (Archive or External) or another project. You can also access this menu item using Ctrl+C.

Paste

Pastes one or more file or folder references from the Windows clipboard to the Archive or External file tab. You can also access this menu item using Ctrl+V.

Select All

Selects all of the files and folder references on the current files tab. You can also access this menu item using Ctrl+A.

Select Inverse

Inverts the current file selection. This will select any file or folder references on the current files tab that aren't already selected, and deselect the ones that are. You can also access this menu item using Ctrl+I.

Preferences...

Opens the Preferences dialog where you can customize the Setup Factory design environment to suit your style.


Project Menu

Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

Add Files...

Opens the Add Files to Project dialog that you can use to add new files to your Setup Factory project. You can also access this menu item using the Insert key.

Tip: You can customize the file filters for adding files by editing a file called _add_files_filters.txt located in Setup Factory's "Data" folder.

Add Folder Reference...

Opens a Folder Browse dialog where you can specify what folder you would like to reference in your project. Once a folder is specified, the Folder Reference Properties dialog is shown where you can customize its settings. You can also access this menu using Ctrl+Insert.

Remove Selected

Removes the currently selected files or folder references from the project. If no file or folder reference is selected, this option will not be available. You can also access this menu item using Delete key.

File Properties...

If a single file is selected, the Single File Properties dialog is opened. If multiple files are selected, the Multiple File Properties dialog is opened. If a single folder reference is selected, the Single Folder Reference Properties dialog is opened. If multiple folder references are selected, the Multiple Folder Reference Properties dialog is opened. You can access this menu item using Ctrl+Enter.

Session Variables...

Opens the Project Settings dialog to the Session Variables tab where you can define the session variables that will be used in your project.

Background Window...

Opens the Project Settings dialog to the Background tab where you can configure the background window of your setup.

System Requirements...

Opens the Project Settings dialog to the Requirements tab where you can configure the installation's system requirements.

Log Files...

Opens the Project Settings dialog to the Logs tab where you can enable the generation of a log file during the installation process.

Advanced Settings...

Opens the Project Settings dialog to the Advanced tab where you can configure settings such as silent installs, user profile settings for shortcuts, the install icon, and setup manifest.

Skin

Opens the Project Settings dialog to the Skin tab where you can apply a skin file to the setup runtime.

Screens...

Opens the Screens dialog where you can specify and manage what screens you would like to display during your install.

Actions...

Opens the Actions dialog where you can create any actions that are needed during your install. These actions would be created on the project events.

Packages...

Opens the Packages dialog where you can create and manage the packages for your install.

Languages...

Opens the Languages dialog where you can define what languages you want to support in your install.

Serial Numbers...

Opens the Security dialog to the Serial Numbers tab where you can configure the serial number lists you wish to include in your install.

Expiration...

Opens the Security dialog to the Expiration tab where you can enable the setup to expire given certain criteria.


Resources Menu

Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

Dependencies...

Opens the Resources dialog to the Dependencies tab where you can select the runtime technologies you want to include in your project. This includes Visual Basic 5.0 and 6.0, Visual C++ 2010, .NET 4, Windows Installer 4.5 and many more.

Primer Files...

Opens the Resources dialog to the Primer Files tab where you can add any primer files you need access to during your install.

Global Functions...

Opens the Resources dialog to the Global Functions tab where you can create common Lua functions that may be used throughout your install.

Script Files...

Opens the Resources dialog to the Script Files tab where you can include external script files (*.lua) in your project.

Plugins...

Opens the Resources dialog to the Plugins tab where you can add action plugins to your project.


Uninstall Menu

Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

Settings...

Opens the Uninstall Settings dialog to the Settings tab where you can configure the core uninstall settings for your application.

Background Window...

Opens the Uninstall Settings dialog to the Background tab where you can configure the background window of your uninstall.

Control Panel...

Opens the Uninstall Settings dialog to the Control Panel tab where you can configure the uninstall's control panel entries.

Shortcut...

Opens the Uninstall Settings dialog to the Shortcut tab where you can configure the uninstall's shortcut settings.

Log Files...

Opens the Uninstall Settings dialog to the Logs tab where you can enable the generation of a log file during the uninstall process.

Screens...

Opens the Uninstall Screens dialog where you can configure the screens you want to appear during the uninstall process.

Actions...

Opens the Uninstall Actions dialog where you can create any actions that are needed during your uninstall. These actions would be created on the uninstall events.


Publish Menu

Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

Build

Starts the build process for the current project. You can also access this menu item using F7.

Stop Build

Immediately aborts the current build process. You can also access this menu item using Ctrl+F7.

Settings

Opens the Build Settings dialog where you can configure the settings you want to use for the build process.


View Menu

Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

Toolbars

Shows or hides the available toolbars.

Standard

Shows or hides the standard program toolbar.

File

Shows or hides the Files toolbar.

Edit

Shows or hides the Edit toolbar.

Project

Shows or hides the Project toolbar.

Resources

Shows or hides the Resources toolbar.

Uninstall

Shows or hides the Uninstall toolbar.

Publish

Shows or hides the Publish toolbar.

Tools

Shows or hides the Tools toolbar.

Help

Shows or hides the Help toolbar.

Filters

Shows or hides the Filters toolbar.

Status Bar

Shows or hides the status bar at the bottom of the Setup Factory main screen.

Tasks

Shows or hides the Tasks panel.

Output

Shows or hides the Output panel.

Archive Tab

Switches to the Archive tab of the file list on the Setup Factory main screen. You can also access this menu item using Ctrl+1.

External Tab

Switches to the External tab of the file list on the Setup Factory main screen. You can also access this menu item using Ctrl+2.

Columns...

Opens the Columns dialog where you can configure the sortable columns you would like to display in your file list for both the Archive and External tabs.

Refresh

Refreshes the properties of all files in the project (refreshes the project window). You can also access this menu item using F5.


Tools Menu

Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

Project Report...

Opens the Generate Project Report dialog where you can create a detailed report of all settings in your project.

Scan File Dependencies...

Opens the Scan Dependencies dialog where you can scan a Portable Executable file for dependencies and add them to your project.

Scan Visual Basic Project...

Opens the Scan Visual Basic Project dialog where you can scan a Visual Basic 5.0 or 6.0 project file for dependencies and add them to your project.

Calculate File CRC...

Opens the Calculate File CRC dialog, where you can calculate the CRC value of any file on your system. This can be useful if you are comparing CRC values during your setup.

Tip: If a file in your file list is currently highlighted, its CRC value will automatically be calculated for you without having to browse for it.

Open Selected File

Opens the currently selected file in your system's default viewer for that file type. You can also access this menu item using Ctrl+D.

Note: This item is not available when multiple files are selected.

Customize...

Opens the Customize dialog where you can create custom toolbars, themes, shortcut keys or link to external programs.


Help Menu

Program Menus

Overview File Edit Project Resources Uninstall Publish View Tools Help

Setup Factory Help

Opens the online help for Setup Factory.

User's Guide

Opens the online help to the user's guide for Setup Factory.

Ordering Information

Opens the Ordering Information topic in the online help where you can find ordering information for Setup Factory.

Buy Now

Opens your web browser to a web page where you can order Setup Factory and other Indigo Rose products online.

Home Page

Opens the your web browser to the Indigo Rose web site.

Technical Support

Opens your web browser to the Technical Support and Software Maintenance page.

User Forums

Opens your web browser to a web page where you can find our online user forums.

Check for Update

Checks the Internet to see if a newer version of Setup Factory is available.

About Setup Factory...

Opens the About dialog which shows the copyright and version information for Setup Factory. Use this whenever you need to find out what version and build of Setup Factory you currently have.


Project File Properties - Overview

Project File Properties

Overview General Statistics

The project file's properties are mainly used for organizational purposes and can only be accessed from within the design environment on the Project File Properties dialog.

To access the Project File Properties dialog, choose File > Properties... from the program menu.

There are two tabs on the Project File Properties dialog:

  • General

  • Statistics


General

Project File Properties

Overview General Statistics

Note: The following information will not be visible in the project's generated runtime.

Filename:

The full path and filename of your Setup Factory project file.

Title:

The title you want to give the current project file.

Author:

The author of the current project.

Company:

The company who created the project.

Copyright:

Copyright information for the current project.

URL:

A URL that may contain company or product information for the project.

Email:

A contact email address.

Comments:

Any additional comments you would like to provide to describe the current project.


Statistics

Project File Properties

Overview General Statistics

Note: The following information will not be visible in the project's generated runtime.

File Size:

The size of the Setup Factory project file.

Created:

The creation date and time of the project file.

Modified:

The date and time of the last modification to the project file.

Accessed:

The date and time the project file was last accessed.

Created Ver:

The full build number the project was created with.

Last Saved Ver:

The full build number the project was last saved with.


Project Settings - Overview

Project Settings

Overview Session Variables Background Requirements Logs Advanced Skin

The Project Settings dialog is where you can configure various installation settings for your project. One section allows you to define a series of built-in and custom session variables for your install. These are used as dynamic placeholders for commonly used values in your setup such as destination paths and product names.

The second category of settings apply to the background window of your install. The background window is a large window that your main installation window will sit on at runtime. The background window may be a solid color, gradient color, or even an image.

The Requirements category provides a easy method of checking the user's system for certain settings that must be in place for your application or install to run. Some of these settings include the target operating system, screen resolution and administrative rights.

Another category that can be found here is the configuration for an installation log file. This is a very useful debugging tool that logs everything that occurs during the execution of your setup, including any errors that may occur.

The Advanced section contains a few advanced settings for your install such as silent mode switches, archive integrity checking, user profile defaults and advanced icon and taskbar representations.

The Skin section allows you to change the appearance of your setup by applying a style or skin file to the runtime.

Each of these categories can be accessed from the Project program menu.

The Project Settings dialog contains the following categories:

  • Session Variables

  • Background

  • Requirements

  • Logs

  • Advanced

  • Skin


Session Variables

Project Settings

Overview Session Variables Background Requirements Logs Advanced Skin

The Session Variables tab is where you can set general information and defaults about your product such as your Product name, Company name, Application Folder, and so on. These values are automatically assigned to built-in session variables that you can use throughout your installation. You can also create custom session variables that behave in the same manner.

Product Information

The Product Information session variables contain information about your product and your company. The following session variables are available in this category:

%ProductName%

The name of your product. For example, "Setup Factory".

%CompanyName%

The name of your company. For example, "Indigo Rose Software".

%ProductVer%

The version of your product. For example, "9.0.0.0".

%Copyright%

A copyright notice for the product. For example, "Copyright © 2015 - Indigo Rose Software".

%CompanyURL%

Your company's website. For example, "http://www.indigorose.com".

%WindowTitle%

The text that will appear on the windows task bar while the installation is running.

%WindowTitleUninstall%

The text that will appear on the windows task bar while the uninstall is running.

Folder Defaults

The Folder Defaults session variables contain the default paths used in your installation. The following session variables are available in this category:

%AppFolder%

The default application directory for your installation. This variable's value may change during the install, for example, through the Select Install Folder screen.

%AppShortcutFolderName%

The default Start Menu application folder for your install. This variable's value may change during the install, for example through the Select Shortcut Folder screen.

Custom

A list of all of the currently defined custom session variables that are available in your install.

Add

Create a new custom session variable and assign a value to it.

Remove

Remove the currently selected custom session variable.

Rename

Rename the currently selected custom session variable.


Background

Project Settings

Overview Session Variables Background Requirements Logs Advanced Skin

The background window is a large window that your main installation window will sit on at runtime. The background window may be a solid color, gradient color, or even an image. Below are the settings used to configure how this background window should look throughout your install.

Show background window

Show a background window behind the main installation window.

Style

Standard

Show a title bar and border for the background window.

Bordered

Show a border around the background window with no title bar.

Kiosk

Make the background window cover the entire screen without a title bar or border.

Appearance

Solid color:

Make the background window a solid color. Click the select button ( [image] ) to bring up a color chooser.

Gradient:

Create a gradient color background by blending two colors together. The first color represents the color that will appear at the top of the background window and the second color represents the bottom color that it will be blended into. You can click the select button ( [image] ) to bring up a color chooser for each color.

Image:

Insert an image into the background window. Click the Browse button to select the image file you want to use. The following image formats are supported:

*.bmp; *.gif; *.jpg; *.pcx; *.png; *.tga; *.tif

Note: The specified image file will be stretched to fit the dimensions of the background window.

Text

Heading:

The text that will appear along the top of the background window. You can click the Font button to choose the font you want to use for the text, and the select ( [image] ) button to choose the text color.

Left

Align the heading text to the left hand side of the background window.

Center

Center the heading text on the background window.

Right

Align the heading text to the right hand side of the background window.

3D

Give the heading text a three-dimensional effect. You can click the select ( [image] ) button to choose the text shadow color you want to use.

Subheading:

The text that will appear below the heading text on the background window. You can click the Font button to choose the font you want to use for the text and the select ( [image] ) button to choose the text color.

Left

Align the subheading text to the left hand side of the background window.

Center

Center the subheading text on the background window.

Right

Align the subheading text to the right hand side of the background window.

3D

Give the subheading text a three-dimensional effect. You can click the select ( [image] ) button to choose the text shadow color you want to use.

Footer:

The text that will appear along the bottom of the background window. You can click the Font button to choose the font you want to use for the text and the select ( [image] ) button to choose the text color.

Left

Align the footer text to the left hand side of the background window.

Center

Center the footer text on the background window.

Right

Align the footer text to the right hand side of the background window.

3D

Give the footer text a three-dimensional effect. You can click the select ( [image] ) button to choose the text shadow color you want to use.


Requirements

Project Settings

Overview Session Variables Background Requirements Logs Advanced Skin

Often software applications have minimum requirements that need to be met for the application to run successfully. The Requirements tab contains a series of common requirements that can automatically be verified at the beginning of the installation. If one or more of the requirements fail, you have the choice of either warning the user with a dialog and continuing, or notifying the user and aborting the installation process.

Operating System

The supported operating systems for the current installation. Some operating systems also allow you to select specific service release options. The operating system list is a tree view that can be expanded for additional categories. You can check all OS boxes that you want to support for the current installation. The main operating system categories are listed below:

  • Any OS (Selecting this option includes all OS's listed below)

  • Windows XP (SP2 or greater)

  • Windows Server 2003

  • Windows Vista

  • Windows Server 2008

  • Windows 7

  • Windows Server 2008 R2

  • Windows 8

  • Windows Server 2012

  • Windows 8.1

  • Windows Server 2012 R2

  • Windows 10

  • Windows Server 10

  • All Future OSs

System Checks

RAM:

The minimum amount of RAM required for your application.

Screen width:

The minimum screen resolution width (in pixels) required for your application.

Screen height:

The minimum screen resolution height (in pixels) required for your application.

Color depth:

The minimum color depth of the user's video display (in bits per pixel) required for your application.

User must have administrative privileges

The user must be logged in with administrative privileges for a successful installation.

Note: This setting propagates through to the uninstall. If the installation requires administrative privileges, the uninstallation will as well.

Note: On Windows Vista or later, with UAC enabled, administrators are logged in with standard user privileges with the ability to elevate. This check will determine if the user has already been elevated to the full access token. See Installing on Windows Vista or Later for more information.

User Notification

Warn user and continue

If any of the specified requirements fail, warn the user and continue with the installation.

Notify user and abort setup

If any of the specified requirements fail, notify the user and abort the setup process.


Logs

Project Settings

Overview Session Variables Background Requirements Logs Advanced Skin

Log File

Create log file

Generate an installation log file during the installation. The installation log file is in ASCII text format and provides information about what happened during the installation, such as which files were installed, which programs were executed, what Registry changes were made, etc. This information can be extremely useful if you ever need to debug an installation where errors occurred.

Filename:

The location and filename of the log file to generate. You can specify an absolute location such as C:\Temp or you can use session variables to form dynamic paths such as %TempFolder%\logfile.txt.

Note: the log file is created at the very start of the setup, before %AppFolder% has been established. You should always create your log files in a pre-existing, standard system directory such as %TempFolder% or %WindowsFolder%.

Write mode:

How the log file will be updated if there is currently a log file in the target location. Choose from:

Append

Append any new log file entries to the end of the existing file.

Overwrite

Overwrite the existing log file when generating the current one.

Include action details:

The action details that will be included in the log file. Choose from:

None

Don't log any errors in scripts in the log file.

Errors

Log errors in scripts with the event the error occurred in, the line it occurred on and the error message or code.

Extended Errors

Same as Errors but the actual line of code executed will be reported as well (if available).


Advanced

Project Settings

Overview Session Variables Background Requirements Logs Advanced Skin

Installation

Enable silent/unattended install

Enable the install to be run in "silent mode" using the /S command line option. This means that there will be no user interaction required during the installation process. If you are performing silent installations, it is highly recommended that you use a log file during the setup process so that you can debug the setup if problems occur.

Note: Screen actions will only be executed if screens are displayed, therefore when run in silent mode, no screen actions will be executed.

Start in silent mode

Start the setup in "silent mode" by default. If unchecked, you can run your setup in silent mode using the command line option /S, for example C:\Output\setup.exe /S. Selecting this option sets the global variable _SilentInstall to true.

Default User Profile for Shortcuts

On Windows NT based operating systems, this option allows you to specify which users the program shortcuts will be created for by default:

Current user only

Create program shortcuts in the current user's profile only. This option sets the boolean global variable _UsePerUserFolders to true.

All users

Create program shortcuts in the "All Users" profile. This option sets the boolean global variable _UsePerUserFolders to false.

Application Settings

Use custom icon:

Display a custom icon in the top left corner of your installation window. It will also be used to represent the installation on the Windows task bar. Click the Browse button to open the Insert File Reference where you can select an existing standard icon (.ico) file from your project's Primer Files list, or add one. After the file has been selected, this field will contain the location to reference the icon file during the installation.

Hide taskbar icon

Hide the taskbar icon during the install.

Always on top

Make the installation window always appear on top of all other windows on the desktop. The window will remain on top even if the user switches to another application.

Requested User Privilege Level

This section specifies which requested execution level to include in the install/uninstall's application manifest for distribution on Windows Vista or later. Installations should generally always be built using the default "Require administrator" setting. Before changing this default setting, see Installing on Windows Vista or Later for important information concerning required changes to your install, and feature limitations.

Note: For more information on the settings below and general Windows Vista/Windows 7/Windows 8/Windows 8.1/Windows 10 information, see Installing on Windows Vista or Later.

As invoker

The setup runs with the same access token as the parent process. For example, if the user is logged in as a standard user, those are the privileges they will inherit during the setup. This option should only be used in special circumstances where you are certain you do not need access to protected areas of the operating system.

Highest available

The setup runs with the highest privileges the current user can obtain. This setting is designed for applications that can be run by all users. It is most useful for applications that require privileges above that of a limited user, but less than a full administrator.

Require administrator (default)

The setup requires to be run with the full access token of an administrator. Generally installations make changes to protected system locations that are typically writable to only by administrator users. This is the default setting for installs created with Setup Factory.


Skin

Project Settings

Overview Session Variables Background Requirements Logs Advanced Skin

Apply skin to runtime

This option controls whether or not the skin file specified in the Skin filename edit field will be applied to the setup runtime.

Note: The setup skin is applied to both the install and uninstall.

Note: Runtime skinning is not compatible with the UPX compression. This type of compression will be skipped if skins are applied.

Skin filename:

The path to the skin file that will be applied to the setup at runtime. Two kinds of skin files are supported:

  • *.msstyles - A Windows XP Visual Style file. There are many msstyles files freely available online, websites such as www.deviantart.com will even have specific categories for them (http://browse.deviantart.com/customization/skins/windows/visualstyle/).

  • *.cjstyles - A CodeJock style file. This can be one of the style files provided by Indigo Rose or one of the many freely available online. Styles can be easily created using the freely available CodeJock ISSkin tool.

Tip: You can find the default skin files in the \Includes\Skins folder of the Setup Factory program folder.

Sub-style:

A list of sub-styles available for the selected skin. Leave this blank to use the default skin style.


Project Wizard - Overview

Project Wizard

Overview General Information Platform Source Folder Window Settings Theme Multilingual Dependencies Optional Features

The Project Wizard is a user friendly means of creating a new project. The wizard allows you to specify your personal/company information, specify the intended platform, set where your files are located, choose a theme for your installer, select various languages, add runtime support, and configure a handful of other features. The project wizard can be used to create a simple, fully functioning install, with no further configuration from you.

To access the Project Wizard, choose File > New from the program menu.

Note: You can optionally disable the Project Wizard from displaying whenever a new project is created by unchecking the Show project wizard option on the Start a New Project dialog, or from the document preferences dialog.

The Project Wizard allows you to configure the following sections of your installer:

  • General Information

  • Platform

  • Source Folder

  • Window Settings

  • Theme

  • Multilingual Settings

  • Runtime Support

  • Optional Features


General Information

Project Wizard

Overview General Information Platform Source Folder Window Settings Theme Multilingual Dependencies Optional Features

The General Information screen is the first screen of the Project Wizard that allows you to configure your personal/company information in your setup.

Below are the General Information options:

What is your company name?

Your company name, for example Indigo Rose Software. This value will be stored in the session variable %CompanyName%.

What is your product's name or title?

Your product's name, for example Setup Factory. This value will be stored in the session variable %ProductName%.

What is your product's version?

The version of your product, for example 9.0. This value will be stored in the session variable %ProductVer%.

What is your company URL?

Your company's website, for example http://www.indigorose.com. This value will be stored in the session variable %CompanyURL%.


Platform

Project Wizard

Overview General Information Platform Source Folder Window Settings Theme Multilingual Dependencies Optional Features

The Platform page of the project wizard allows you to specify the desired platform of your setup.

This decision should be made based on the platform (either 32-bit or 64-bit) of the application or files you are distributing.

The Project Wizard will automatically configure the Platform setting in the Build Settings to use this platform, however it can be changed at any time. If you would like to support both platforms in a single project, this can be accomplished at a later time through the use of build configurations. Build configurations can be created and modified on the Build Settings dialog which can be accessed by choosing Publish > Settings from the program menu.

Select one of the following platforms:

32-bit

Select this option if you are creating a setup for a 32-bit application.

Note: 32-bit setup files will run on both 32-bit and 64-bit operating systems.

64-bit

Select this option if you are creating a setup for a 64-bit application.

Note: 64-bit setup files will fail to run on 32-bit operating systems.


Source Folder

Project Wizard

Overview General Information Platform Source Folder Window Settings Theme Multilingual Dependencies Optional Features

The Source Folder page of the project wizard allows you to specify the location of the files you want to include in your setup.

What folder are your files located in?

The full path to the folder that contains all of the files you want to include in your installer. Setup Factory will add file references into your project for every file that exists in this folder. You can click the Browse button to select a folder.

Include files in subfolders

Whether or not to add files found in any subfolders of the specified path. If checked, every file existing within the path provided will be included, whether it is in the root of the specified path, or within a subfolder.

Note: If you opt to include files in subfolders, every file within the given path will be included. For example, if you specified 'C:\' as your path, and chose to include files in subfolders, every file from the C: drive would be included into your installer.


Window Settings

Project Wizard

Overview General Information Platform Source Folder Window Settings Theme Multilingual Dependencies Optional Features

Wizard

Configures your installer to run as a wizard style application, much the same as the Project Wizard.

Wizard with background window

Configures your installer to run as a wizard style application, with a background window.

Solid Color

Specifies a solid color for the background window.

Gradient

Specifies a two-color gradient for the background window.

Image

Specifies an image to show as the background window. You can either type in the path manually, or click the Browse button.


Theme

Project Wizard

Overview General Information Platform Source Folder Window Settings Theme Multilingual Dependencies Optional Features

Setup Factory comes with several themes for you to choose from. By selecting one other than the default, you can add that extra flare to your project. Your theme can be configured at any point from the theme dialog.

Project Theme:

The project theme that your installer will use.

Note: The project theme selected will be used by default on all screens. To customize the look and feel of any individual screen in your project, edit the screen style from the screen properties dialog.


Multilingual

Project Wizard

Overview General Information Platform Source Folder Window Settings Theme Multilingual Dependencies Optional Features

Setup Factory supports the use of multiple languages in your installations. See the languages topic for more information.

What languages do you want your setup to support?

The languages that will be supported by your setup.

Which language should be used by default?

The language that your setup will use by default.


Runtime Support

Project Wizard

Overview General Information Platform Source Folder Window Settings Theme Multilingual Dependencies Optional Features

Dependency modules are basically any technologies that your software requires in order to function. The Visual Basic runtime files are an excellent example of a dependency.

Which, if any, of these technologies does your application use?

The dependency modules that will be included with your setup.

Scan Visual Basic project file for dependencies:

Scans a Visual Basic project file for dependencies and adds them to your project. Enabling this feature is the same as choosing Scan Visual Basic Project from the Tools menu.

Visual Basic version:

The version of Visual Basic that your Visual Basic project file was created with.


Optional Features

Project Wizard

Overview General Information Platform Source Folder Window Settings Theme Multilingual Dependencies Optional Features

The optional features tab is where you can configure the options that by default will work with most setups, such as whether to create an uninstall.

Include uninstall support

Whether to create an uninstall for your software. This option can be changed later from the Uninstall Settings dialog.

Create a log file during installation (and uninstallation)

Whether to create a log file during the installation and uninstallation.

Warn the user if they don't have with Administrative privileges

If checked, and the setup is run on a system without administrative privileges, the user is alerted, and the setup will not continue.

Tip: Use this option when changing system settings, or when writing to a folder where permissions are required, such as Windows or Program Files.

Operating systems supported (required) by your software:

What operating systems (OS's) are supported by your software. The installer will not run on any OS which is unchecked.


Resources - Overview

Resources

Overview Dependencies Primer Files Global Functions Script Files Plugins

Project Resources are those 'behind the scenes' items in your installation which allow it to function properly. These include any special runtime files that your software product requires in order to function properly, any files that are required during your installation, any plugins utilized by your installation, and any globally declared functions and script files used.

  • Dependencies

  • Primer Files

  • Global Functions

  • Script Files

  • Plugins


Dependencies

Resources

Overview Dependencies Primer Files Global Functions Script Files Plugins

Many of today's development tools require that you distribute certain runtime files along with your application. In Setup Factory, these are referred to as dependency modules.

Dependency modules are run at the very beginning of the setup, before any screens are displayed or any project actions are executed. All dependency modules that have been added to the list will be executed sequentially in top-down order as they appear at design time. Each module will execute its own detection script and if required, run its installation script. If any module is determined as not required from its detection script, the next module will be run.

While dependency modules are often used to detect and install, they can also simply be used as detection for technology for used in your install.

Dependency modules can easily be created on your own, or you can download available modules from the Indigo Rose web site, www.indigorose.com.

Tip: You can create new modules by selecting Create new module... from the Advanced button on the Dependencies dialog. Another quick way to create a new module is to modify one of the existing modules and then select Export module... from the Advanced button so you can use it in other projects. You can also include modules from other locations by selecting Browse for module... from the Advanced button.

Please consult your development tool's documentation to determine what files or technology you need to distribute with your software.

Dependency modules to build into the setup:

A list of the dependency modules that are currently selected to be included in your project.

Name

The names of the modules that will be included in your project.

Description

Brief descriptions of each module.

Build Configurations

The build configurations that each dependency module is a part of.

Add

Open the Add Dependency Module dialog so you can add a new dependency module to the current project.

Remove

Remove the currently selected dependency module from the setup.

Edit

Open the Dependency Module Properties dialog so you can edit the currently selected dependency module.

Move Up ( )

Move the selected dependency module up one position in the list. The order in the list represents the order in which the modules will be merged with your project file at build time.

Move Down ( )

Move the selected dependency module down one position in the list. The order in the list represents the order in which the modules will be merged with your project file at build time.

Advanced

Export module...

Export the current dependency module settings to a file (*.XML).

Create new module...

Create a new dependency module.

Browse for module...

Browse your system for a dependency module file (*.XML).

More Modules

Open your web browser to a web page where you can find more Setup Factory dependency modules.


Primer Files

Resources

Overview Dependencies Primer Files Global Functions Script Files Plugins

The Primer Files tab is where you can edit the list of primer files that will be included in the setup executable. The files in this list will be extracted from the setup executable before the installation process begins so they can be used at the very start of the installation process, right after the user runs the setup executable.

Any files listed in the Primer files list will be extracted immediately to the setup executable's temporary directory when the setup begins. You can access these files by using the %TempLaunchFolder% session variable.

For example, if you added "C:\My Program\Checker.exe" to the Primer files list, you could access the Checker.exe program at the beginning of the installation by using the following path: %TempLaunchFolder%\Checker.exe

To access the Primer Files dialog, choose Resources > Primer Files... from the program menu.

Files to extract to %TempLaunchFolder% when the setup starts:

Filename

The full path and filenames of all primer files currently added to the project.

Build Configurations

The build configurations that each file is a part of.

Delete On Exit

Whether each file will be deleted when the install exits. If True is shown, the file will be deleted and if False is shown, the file will be left on the user's system.

Used By Uninstall

Whether each file will be used by the uninstall program.

Add

Opens the Primer File Properties dialog where you can add a new primer file to the setup.

Remove

Remove the currently selected primer file from the setup.

Edit

Opens the Primer File Properties dialog where you can edit the properties of the currently selected primer file.


Global Functions

Resources

Overview Dependencies Primer Files Global Functions Script Files Plugins

The Global Functions dialog is a convenient place to include any functions or variables that you want to make available throughout your setup. Any functions or variables that you add here will be available right after your installation is launched.

Note: Any script that you add on this dialog will be performed before the On Startup event is triggered.

To access the Global Functions dialog, choose Resources > Global Functions... from the program menu.

Global functions:

The area (code window) where you can either type in your actions, or add them through the action wizard to create your global functions.

Quick Help:

When the cursor is on an action in the code window, its action definition will be displayed in this field.

Action Help

When the cursor is on an action in the code window, its online help will be opened.

Add Action

Adds a new action to the current event through the action wizard.

Add Code

Displays a variety of code templates you can add to the code window.

Edit

Edit the action's properties after it has been added to the code window. When the cursor is on an action in the code window, the Edit button will display its properties dialog where you can modify its settings.

Bookmarks

Create and manage bookmarks in the code window so you can easily jump to specific spots in your code.

Macros

Allows you to record and play macros so you can replicate frequent code scripts in the code window.

Advanced

Advanced options that are available in the Global Functions dialog:

Open...

Opens a script file (*.lua) and displays its contents in the code window.

Save...

Saves the current script in the code window as a script file (*.lua).

Print...

Prints the action script currently in the code window.

Syntax Check

This option checks the current script to make sure it is syntactically correct. It does not check for logical or other programming errors, simply syntax.

Note: You can turn on automatic syntax checking from Edit > Preferences on the Script Editor page.

Double-click Edit

Allow double-clicking on actions in the code window to edit their properties (Properties dialog will be displayed).

Note: If Double-click Edit is unchecked, double-clicking any text in the action editor simply selects the text, as in most other text editors. This option can also be set in Edit > Preferences on the Script Editor page.

Editor Settings...

Opens the action editor's Window Properties dialog where you can customize its settings.

Global Functions...

Opens a dialog where you can create any Global Functions you wish to include in your project.

Import Registry Values...

Opens the Import Registry Key/Values dialog where you can import keys or values from the Registry on your development system.

Import .REG File...

Opens a file browse dialog where you can select a .REG file that you would like to recreate using Setup Factory Registry actions.


Script Files

Resources

Overview Dependencies Primer Files Global Functions Script Files Plugins

The Script Files dialog allows you to add or remove Indigo Rose, or custom created script files (*.lua) to or from your project. The Lua script within these files will be read and included in your install at build time. This enables any code within them to be called anywhere during your install.

This feature allows you to share generic script files that are used by many projects without having to copy the code into the project each time. This also adds the convenience of maintaining the code in one file if future changes need to be made.

To access the Script Files dialog, choose Resources > Script Files... from the program menu.

Each script file that is provided by Indigo Rose contains a summary of its contents at the top of the file which can be viewed in any text editor, such as Notepad. For example, at the beginning of the Detect_Acrobat.lua script file, you will see the following information:

--[[
**********************************************************************************
Function: ir_GetAcrobatVersion()
Purpose: Detects the existence of Adobe Acrobat Reader / Adobe Acrobat
Arguments: None.
Returns: Version number, 0.0.0.0 if Acrobat / Acrobat Reader does not exist
**********************************************************************************
]]

This script file, like many others contains a function that can be called anywhere in your install. To call it, simply add a line in one of the action scripts that calls the function ir_GetAcrobatVersion(), which in this case will return the version number of Adobe Acrobat.

For example, if you wanted to abort the install if the user's version of Acrobat is less than 5.0.0.0, the following script could be added to any action event in your project:

-- Get the version of Acrobat that is installed.
strAcroVer = ir_GetAcrobatVersion();

-- Compare the version number from Acrobat with "5.0.0.0" and check if it is less than 5.0.0.0.
if (String.CompareFileVersions(strAcroVer, "5.0.0.0") == -1) then
-- Exit the setup.
Application.Exit(0);
end

Filename

The full path and filenames of the script files that will be added to your install at build time.

Note: Setup Factory may automatically include script files needed by its runtime. One example of a script file that will automatically be added to your project is called _SUF70_Global_Functions.lua. If this is the case, they should not be modified unless you are sure the project does not require it. Under normal circumstances you should never remove script files you did not add yourself.

Build Configurations

The build configurations that each script file belongs to.

Add

Opens the Global Script File Properties dialog where you can add a new script file to your project. There are a variety of Indigo Rose created script files that are shipped with Setup Factory. All available script files can be found in the Scripts folder, normally located in C:\Program Files\Setup Factory 9\Includes\Scripts. An example of a file that can be found there is Detect_Acrobat.lua.

Remove

Removes the currently selected script file from your project.

Note: Caution should be taken when removing script files. Only custom script files should be removed from a project.

Edit

Opens the Global Script File Properties dialog where you can edit the properties of the currently selected script file. These properties include its file path and build configurations.

Up ( )

Move the selected script file up one position in the script file list.

Down ( )

Move the selected script file down one position in the script file list.

Edit Script(s)

Opens the selected script file(s) in the Indigo Rose Script Editor application where you can edit its contents.


Plugins

Resources

Overview Dependencies Primer Files Global Functions Script Files Plugins

Action plugins are actions that are external to the Setup Factory program. They are independently developed and distributed and can be integrated into your projects to extend their functionality. Some action plugins may be developed by Indigo Rose, while others may be developed by third parties. You can refer to the action plugin's documentation (click the About Plugin button after adding it) for information on what features it adds and how to use them.

Note: As of Setup Factory 9, only plugins created with version 2.0 of the SDK (or higher) are supported.

Note: Any action plugins that are located in Includes\Plugins within the Setup Factory program directory and that were created with version 2.0 (or higher) of the Plugin SDK will be available through the design environment by choosing Resources > Plugins... from the program menu and clicking the Add button.

Note: Action plugins may be available in either 32-bit or 64-bit. You must ensure you choose the version of the plugin that matches the chosen setup platform (32-bit or 64-bit).

Setup Factory ships with the Zip Actions Plugin, Clipboard Actions Plugin (32-bit and 64-bit) and FTP Actions Plugin (32-bit and 64-bit), however there are many others that can be integrated into your setups.

All available plugins can be found on the Indigo Rose Website or by clicking the More Plugins button on this dialog.

Plugins to build into the setup:

A list of the action plugins that are currently selected to be included in your project.

Name

The names of the action plugins that will be included in your project.

Build Configurations

The build configurations that each action plugin is a part of.

Add

Opens the Add Action Plugin dialog where you can add a new action plugin to the your project.

Remove

Remove the currently selected action plugin from your project.

Build Configurations

Opens the Plugin Build Configurations dialog where you can specify which build configurations you want the selected action plugin to be a part of.

About Plugin

Opens the About Plugin dialog for the selected plugin containing information such as the name, file, version and copyright information. On the About Plugin dialog you will also find a Plugin Help button which will open a document that provides details about its features and usage.

Note: If the action plugin was developed by a third party, details about its features and usage may vary.

More Plugins

Opens your default web browser to a location where you can find any additional action plugins that are available.


Screens - Overview

Screens

Overview Theme Before Installing While Installing After Installing

The Screens dialog is where you can add, remove, arrange, preview, export and configure all of the screens you want to show during the installation of your application.

The first category contains the current, and available project themes. Project themes allow you to define a style or "theme" that you would like to apply to all of the screens in your install without configuring each screen manually.

Tip: Themes are very much like "skins" for your setup. If you'd like to create your own themes, see Screen Dimensions and How Screens Are Drawn for some useful information.

Following the Theme tab are the Before Installing, the While Installing, and the After Installing tabs. These represent the three different times during the installation process when screens can be shown.

At run time, the screens are displayed in the same order as they're listed on these tabs.

Screen text can also be translated for each language that is supported by your setup. A language selector can be found on the Settings tab of each screen's properties dialog so you can quickly translate this text.

To access the Screens dialog, choose Project > Screens... from the program menu.

The following four tabs can be found on the Screens dialog:

  • Theme

  • Before Installing

  • While Installing

  • After Installing


Theme

Screens

Overview Theme Before Installing While Installing After Installing

Project themes are a set of visual attributes that are applied to all of the screens in your install to give them a uniform look and feel. These attributes include the color, banner styles, images, text fonts and many more. Using a project theme provides a visual consistency throughout your install. These themes are stored globally and can be used for all of your projects.

Tip: Themes are very much like "skins" for your setup. If you'd like to create your own themes, see Screen Dimensions and How Screens Are Drawn for some useful information.

Tip: Themes can also be stored externally such as on a network drive allowing you to share themes between products and developers. See the Additional themes folder preference for further information.

Preview

An image preview of an example screen given the selected project theme. This theme will be applied to all screens in your project unless it is overridden on a per screen basis using the Override project theme option on the Style tab of each screen's properties.

Preview banner style:

The banner style you want to use in the screen preview.

Top

Show a top banner when previewing a screen.

Side

Show a side banner when previewing a screen.

None

Don't show any banner when previewing a screen.

Project theme:

The current project theme that will be applied to your project screens. You can click the select button to select a different project theme.

Save As

Save the selected project theme under the specified name.

Note: Saved themes will be stored in a "Themes" folder located in the all user profile of Application Data. For example: C:\Documents and Settings\All Users\Application Data\IndigoRose\Setup Factory\9.0\Themes

Edit

Opens the Theme Properties dialog where you can edit the properties of the selected project theme.

Note: You cannot edit the default Setup Factory theme. You must first save the theme under a different name in order to edit its properties.

Remove

Remove the currently selected theme from the global list. Removing a theme means it will no longer be available to any project, so caution should be taken.

Note: You cannot remove the default Setup Factory themes.


Before Installing

Screens

Overview Theme Before Installing While Installing After Installing

The screens listed on the Before Installing tab will be shown before any files are installed onto the user's system and before the While Installing screen is shown. Each screen will be shown in sequential order, the first screen being shown right after the installation is launched.

Screens:

The screens that will appear after the installation starts, up until the point in which the files are going to be installed. The order that these screens appear in the list is the order that they will be shown at runtime.

Screen ID

The identifiers of all of the currently added screens to be displayed before the files are installed.

Screen Type

The screen types of all of the currently added screens.

Preview:

An image preview of the selected screen.

Note: Some contents of the screen preview may not be accurate if it requires information that must be gathered during the installation process.

Add

Open the Screen Gallery dialog where you can add a new screen to the screen list.

Remove

Remove the selected screen from the screen list.

Edit

Open the selected screen's properties dialog where you can configure its settings.

Up ( )

Move the selected screen up one position in the Before Installing screen list.

Down ( )

Move the selected screen down one position in the Before Installing screen list.

Advanced

Add to Gallery...

Opens the Add to Gallery dialog where you can add a custom screen to the global screen gallery.

Export Language

Expands to a menu containing all languages in the project available for export. Clicking on a language will open a Save As dialog so you can choose the path that the selected language will be exported to. A dialog message will notify you of success or failure.

Import Language...

Open a file browse dialog so you can select a screen's language XML file that you want to import into the currently selected screen. A dialog message will notify you of success or failure.


While Installing

Screens

Overview Theme Before Installing While Installing After Installing

The While Installing tab is used to configure the type of progress screen you want to show while your application's files are being installed.

Show progress screen during install

Whether to show a progress screen during the installation.

Progress Screen

Type:

The type of progress screen currently configured to display during the installation of the files.

Change

Open the Screen Gallery dialog where you can select a different progress screen.

Edit

Open the selected progress screen's properties dialog so you can configure its settings.

Preview

An image preview of the currently selected progress screen.

Note: Since this screen displays dynamic content during the installation, some content will not appear during a preview of the screen.

Advanced

Add to Gallery...

Opens the Add to Gallery dialog where you can add a custom progress screen to the global screen gallery.

Export Language

Expands to a menu containing all languages in the project available for export. Clicking on a language will open a Save As dialog so you can choose the path that the selected language will be exported to. A dialog message will notify you of success or failure.

Import Language...

Open a file browse dialog so you can select a screen's language XML file that you want to import into the currently selected screen. A dialog message will notify you of success or failure.


After Installing

Screens

Overview Theme Before Installing While Installing After Installing

The screens listed on the After Installing tab will follow the progress screen configured on the While Installing tab. At this point, all files have been installed onto the user's system. Each screen will be shown in sequential order from top to bottom.

Screens:

The screens that will appear after the files have been installed. The order that these screens appear in the list is the order that they will be shown at runtime.

Screen ID

The identifiers of all of the currently added screens to be displayed after the files have been installed.

Screen Type

The screen types of all of the currently added screens.

Preview:

An image preview of the selected screen.

Note: Some contents of the screen preview may not be accurate if it requires information that must be gathered during the installation.

Add

Open the Screen Gallery dialog where you can add a new screen to the screen list.

Remove

Remove the selected screen from the screen list.

Edit

Open the selected screen's properties dialog where you can configure its settings.

Up ( )

Move the selected screen up one position in the After Installing screen list.

Down ( )

Move the selected screen down one position in the After Installing screen list.

Advanced

Add to Gallery...

Open the Add to Gallery dialog where you can add a custom screen to the global screen gallery.

Export Language

Expands to a menu containing all languages in the project available for export. Clicking on a language will open a Save As dialog so you can choose the path that the selected language will be exported to. A dialog message will notify you of success or failure.

Import Language...

Open a file browse dialog so you can select a screen's language XML file that you want to import into the currently selected screen. A dialog message will notify you of success or failure.


Screen Dimensions

Overview

Screen dimensions (illustration)

Table of screen dimensions and coordinates

Body, top banner and side banner image locations (illustrations)

Table of Screen Dimensions and Coordinates

Here are the sizes and coordinates for the different parts of each screen in Setup Factory:

Part | Size | Coordinates
Total screen client area (the part that gets drawn on) including footer | 497x362 | 0,0 - 497,362
Total screen client area not including footer | 497x312 | 0,0 - 497,312
Top banner area | 497x63 | 0,0 - 497,63
Top separator (2 pixels tall - drawn over the bottom 2 pixels of the top banner area) | 497x2 | 0,61 - 497,62
Footer area | 497x50 | 0,312 - 497,362
Footer separator (2 pixels tall - drawn over the top 2 pixels of the footer area) | 497x2 | 0,313 - 497,314
Body background image | up to 497x362 | upper left corner at 0,0
Side banner image | up to 497x362 | upper left corner at 0,0
Top banner image | up to 497x362 | upper right corner at 497,0

Body and Banner Image Locations

(Scroll down to see the illustrations.)

A body image with the Fill Footer option disabled:

A body image with the Fill Footer option enabled:

A side banner image:

A top banner image:

The body and side banner images are positioned in the upper left corner, and the top banner image is positioned in the upper right corner:


How Screens Are Drawn

Overview

Note: This topic assumes the screen is based on one of the default themes. If you want to increase the size of your screens, you need to create a new screen theme with the desired width and height, or override the project theme on a per-screen basis from the style tab of each screen's properties and set the desired width and height. Image dimensions will vary by screen size. (The default theme size of 497x362 is assumed in the examples below.)

How screens are drawn

A typical screen being drawn (illustrations)

Using full-size banner images

How Screens Are Drawn

  1. The entire client area (i.e. all of the window except the window border and title bar) is filled with the body background color.

  2. The body image is drawn in the upper left corner (0,0), starting from the upper left corner and extending towards the lower right.

  3. (OPTIONAL) The banner is drawn. Depending on the banner setting, this consists of:

No Banner Style: (Banner style is "None")

3a. Nothing happens

Side Banner Style: (Banner style is "Side")

3a. The side banner image is drawn in the upper left corner (0,0), starting from the upper left corner and extending towards the lower right.

Top Banner Style: (Banner style is "Top")

3a. The top banner rectangle is filled with the top banner color.

3b. The top banner image is drawn in the upper right corner (497,0), starting from the upper right corner and extending towards the lower left. (The upper right corner of the image will be at 497,0.)

3c. (OPTIONAL) The header separator is drawn over the bottom two pixels of the top banner rectangle. (0,61 - 497,62)

Note: The header separator is only drawn if the header separator option is enabled.

3d. The top banner text is drawn.

  4. If the Fill Footer option is disabled (false), the footer rectangle is filled with the footer color. If the Fill Footer option is enabled (true), the footer rectangle is left uncolored so the body image is allowed to fill the footer area (if it's large enough).

  5. (OPTIONAL) The footer separator is drawn over the top two pixels of the footer banner rectangle. (0,313 - 497,314)

Note: The footer separator is only drawn if the footer separator option is enabled.

  6. The controls (i.e. navigation buttons, screen controls, etc.) are drawn.

Note: If any of the images are larger than the screen, they will be cropped to 497x362 during the build process (i.e. the parts that extend beyond the window are cut off) in order to shorten load times and reduce storage space at run time.

A Typical Screen Being Drawn

The following nine illustrations demonstrate the steps involved in displaying a typical Select Shortcut Folder screen in the "top banner" style.

Using Full-Size Banner Images

Note that the side banner image and the top banner image can be any size up to 497x362 for the default themes. (It can be larger if you use a theme with a larger width and height.) In fact, the side banner image and the top banner image can be as large as the body image and cover the whole screen. This allows you to create themes that have a completely custom look across the entire screen for each of the three banner styles. Simply create three 497x362 images: a body background image, a side banner image, and a top banner image. The body background image will be used for the "no banner" style, the side banner image will be used for the "side banner" style, and the top banner image will be used for the "top banner" style.

For example, here is a theme that uses a full-size side banner image to put a custom background behind the screen's control area:

The theme's top banner image also covers the whole screen to create a different effect that matches the way the controls are laid out when the top banner style is used:

The theme's body background image on its own provides a suitable backdrop for the layout of the "no banner" style:

Note: The body background image is drawn for all three banner styles (none, side and top)...in the theme pictured above, the side banner image and the top banner image are drawn on top of the body background image, blocking it out.


Screen Types - Overview

Screen Types

Overview

Setup Factory contains various types of screens, each with their own unique features for presenting and gathering information. Each pre-made screen that is available was based upon one of these screen types. While it is convenient to use one of the pre-made screens that are available, there may be occasions where you would like a slightly different layout. For this reason, these screen types can be customized to suit your particular install needs beyond the standard scenario.

The following screen types are available in Setup Factory:

  • Buttons

  • Check Boxes

  • Combo Boxes

  • Custom

  • Custom Progress

  • Edit Fields

  • License Agreement

  • List Box

  • Progress Bars

  • Radio Buttons

  • Scrolling Text

  • Scrolling Text Progress

  • Select Install Folder

  • Select Packages

  • Select Shortcut Folder

  • Static Text


Overview

Buttons Screen

Overview Properties Advanced Examples

The Buttons screen is one type of screen available in Setup Factory that was designed to allow you to present a maximum of 6 clickable buttons combined with description text for each. From each of these button controls, you have full control over what actions you wish to execute when the user clicks them.

The Buttons screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or from the uninstall's Before Uninstalling or After Uninstalling tabs.

This screen type contains the following two categories of settings and some examples:

  • Properties

  • Advanced

  • Examples


Properties

Buttons Screen

Overview Properties Advanced Examples

The Buttons screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Top:

The text you want to appear at the top of the screen, above all of the buttons.

Bottom:

The text you want to appear at the bottom of the screen, below all of the buttons.

Buttons

ID

The control IDs of each button on the current screen.

Label

The text label of each button on the current screen.

Note: Using the ampersand character (&) in a button's label text will make the character to its right a mnemonic key for the control.

Description

The description text associated with each button on the current screen.

Add

Open the Button Properties dialog where you can add a new button to the current screen.

Note: The maximum number of buttons on the screen is 6.

Remove

Remove the currently selected button from the screen.

Edit

Open the Button Properties dialog where you can edit the properties of the currently selected button.

Up ( )

Move the selected button up one position in the button list.

Down ( )

Move the selected button down one position in the button list.

Options

Height:

The height (in pixels) of all of the buttons.

Width:

The width (in pixels) of all of the buttons.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Buttons screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Buttons Screen

Overview Properties Advanced Examples

The following table contains the necessary information to manage and manipulate this screen at run time.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Instructions (bottom) | Static Text | CTRL_STATICTEXT_BOTTOMINSTRUCTIONS | IDS_CTRL_STATICTEXT_BOTTOMINSTRUCTIONS
Button labels | Static Text | CTRL_STATICTEXT_LABEL_01 ... CTRL_STATICTEXT_LABEL_06 | IDS_CTRL_STATICTEXT_LABEL_01 ... IDS_CTRL_STATICTEXT_LABEL_06
Buttons | Button | CTRL_BUTTON_01...CTRL_BUTTON_06 | IDS_CTRL_BUTTON_01 ... IDS_CTRL_BUTTON_06
Timer | Timer | N/A | N/A


Examples

Buttons Screen

Overview Properties Advanced Examples

This example shows how you can detect when a button is pressed on the Buttons screen and react using action script. The action script below can be found by default on the On Ctrl Message event tab when a Buttons screen is added to your project. The On Ctrl Message event can be found on the Actions tab of the screen's properties.

-- These actions are triggered by the controls on the screen.
if (e_MsgID == MSGID_CLICKED) then
-- a control was clicked...
if (e_CtrlID == CTRL_BUTTON_01) then
-- Insert your button handling code here

Dialog.Message("Click","You clicked on Button 01", MB_OK, MB_ICONNONE);
end

if (e_CtrlID == CTRL_BUTTON_02) then
-- Insert your button handling code here

Dialog.Message("Click","You clicked on Button 02", MB_OK, MB_ICONNONE);
end
end

This action script first detects the message ID to see if a button was clicked. If a button control was clicked, a check is then performed to see which one was actually clicked using their control IDs. This example shows a dialog message being shown, however this can be replaced with custom action script to handle your setup needs. For example, you could open a file using the File.Open action.


Overview

Check Boxes Screen

Overview Properties Advanced Examples

The Check Boxes screen is one type of screen available in Setup Factory that was designed to allow you to present a user selection interface via check boxes. The maximum number of check boxes that can be added on this screen is 32 with a maximum horizontal layout of 4 columns.

The Check Boxes screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing, After Installing, Before Uninstalling or After Uninstalling tabs.

This screen type contains the following two categories of settings and some examples:

  • Properties

  • Advanced

  • Examples


Properties

Check Boxes Screen

Overview Properties Advanced Examples

The Check Boxes Screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Top:

The text you want to appear at the top of the screen, above all of the check boxes.

Bottom:

The text you want to appear at the bottom of the screen, below all of the check boxes.

Check Boxes

ID

The control IDs of each check box on the current screen.

Label

The text label of each check box on the current screen.

Note: Using the ampersand character (&) in a label's text will make the character to its right a mnemonic key for the control.

LUA Variable

The LUA variable that each check box's state will be stored in.

Add

Open the Check Box Properties dialog where you can add a new check box to the current screen.

Remove

Remove the currently selected check box from the screen.

Edit

Open the Check Box Properties dialog where you can edit the properties of the currently selected check box.

Up ( )

Move the selected check box up one position in the check box list.

Down ( )

Move the selected check box down one position in the check box list.

Options

Number of columns:

The number of check box columns you want to show. The maximum number of columns is 4.

Distribute:

The layout you want to have for the check boxes. Choose from:

Vertical

Distribute the check boxes vertically from top to bottom.

Horizontal

Distribute the check boxes horizontally from left to right.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The check boxes screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Check Boxes Screen

Overview Properties Advanced Examples

The following table contains the necessary information to manage and manipulate this screen at run time.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Instructions (bottom) | Static Text | CTRL_STATICTEXT_BOTTOMINSTRUCTIONS | IDS_CTRL_STATICTEXT_BOTTOMINSTRUCTIONS
Check boxes | Check Box | CTRL_CHECK_BOX_01 ... CTRL_CHECK_BOX_32 | IDS_CTRL_CHECK_BOX_01 ... IDS_CTRL_CHECK_BOX_32
Timer | Timer | N/A | N/A


Examples

Check Boxes Screen

Overview Properties Advanced Examples

These examples show how you can detect whether or not a checkbox was checked on a Check Boxes screen, and react using action script. Each of the action script examples below can be copied to the On Next event (before the Screen.Next action) of a default Check Boxes screen to see their functionality. The On Next event can be found on the Actions tab of the screen's properties.

Example 1

-- Create a string to hold the checkbox states that were checked to be displayed in the dialog box.
strTheseChecked = "The following checkboxes were checked:\r\n";

-- Check if the first checkbox was checked.
if (check01) then
-- Get the properties of the first checkbox.
tbCheck1 = DlgCheckBox.GetProperties(CTRL_CHECK_BOX_01);

-- Add the variable name of the checkbox and its label it to the dialog string.
strTheseChecked = String.Concat(strTheseChecked, tbCheck1.Text.." - check01\r\n");
end

-- Check if the second checkbox was checked.
if (check02) then
-- Get the properties of the second checkbox.
tbCheck2 = DlgCheckBox.GetProperties(CTRL_CHECK_BOX_02);

--- Add the variable name of the checkbox and its label it to the dialog string.
strTheseChecked = String.Concat(strTheseChecked, tbCheck2.Text.." - check02\r\n");
end

-- Check if the third checkbox was checked.
if (check03) then
-- Get the properties of the third checkbox.
tbCheck3 = DlgCheckBox.GetProperties(CTRL_CHECK_BOX_03);

--- Add the variable name of the checkbox and its label it to the dialog string.
strTheseChecked = String.Concat(strTheseChecked, tbCheck3.Text.." - check03\r\n");
end

-- Check if the fourth checkbox was checked.
if (check04) then
-- Get the properties of the fourth checkbox.
tbCheck4 = DlgCheckBox.GetProperties(CTRL_CHECK_BOX_04);

--- Add the variable name of the checkbox and its label it to the dialog string.
strTheseChecked = String.Concat(strTheseChecked, tbCheck4.Text.." - check03\r\n");
end

-- Display a dialog containing the states of each checkbox.
-- Check if at least one of the checkboxes are checked.
if (check01 or check02 or check03 or check04) then
Dialog.Message("Checkboxes", strTheseChecked, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
-- No checkboxes were checked.
Dialog.Message("Checkboxes", "No checkboxes were checked.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end

This action script demonstrates how to check which of the four default check boxes were checked. This is accomplished by checking the state of the Lua variable that is assigned to each checkbox. These variables contain a Boolean value of either true or false. If a check box has been checked, its label is retrieved and added to a string so that it can be shown at the end.

Example 2

-- Check if the first check box was checked.
-- If it is checked, open a readme text file.
if (check01) then
-- The first check box was checked. Open a readme text file.
File.Open(SessionVar.Expand("%AppFolder%").."\\readme.txt");
end

-- Check if the second checkbox was checked.
-- If it is checked, run the installed application.
if (check02) then
-- The second check box was checked. Run the application.
File.Run(SessionVar.Expand("%AppFolder%").."\\MyProg.exe", "", "", SW_SHOWNORMAL, false);
end

This action script example illustrates how you can optionally open a readme file and launch your application if this screen was added at the end of your install. The above script can be added to a default Check Boxes screen when only the first two check boxes are present.


Overview

Combo Boxes Screen

Overview Properties Advanced Examples

The Combo Boxes screen is one type of screen available in Setup Factory. It was designed to allow you to present a selectable drop down to the user to make choices during the install. The maximum number of combo box fields that can be added on this screen is 4.

The Combo Boxes screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing, After Installing, Before Uninstalling or After Uninstalling tabs.

This screen type contains the following two categories of settings and some examples:

  • Properties

  • Advanced

  • Examples


Properties

Combo Boxes Screen

Overview Properties Advanced Examples

The Combo Boxes screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Top:

The text you want to appear at the top of the screen, above all of the combo boxes.

Bottom:

The text you want to appear at the bottom of the screen, below all of the combo boxes.

Combo Boxes

ID

The control IDs of each combo box on the current screen.

Label

The text label of each combo box on the current screen.

Note: Using the ampersand character (&) in a label's text will make the character to its right a mnemonic key for the control.

Session Variable

The unique session variable that each combo box's value will be stored in at runtime.

Add

Opens the Combo Box Properties dialog where you can add a new combo box to the current screen.

Remove

Remove the currently selected combo box from the screen.

Edit

Opens the Combo Box Properties dialog where you can edit the properties of the currently selected combo box.

Up ( )

Move the selected combo box up one position in the combo box list.

Down ( )

Move the selected combo box down one position in the combo box list.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Combo Boxes screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Combo Boxes Screen

Overview Properties Advanced Examples

The following table contains the necessary information to manage and manipulate this screen at run time.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Instructions (bottom) | Static Text | CTRL_STATICTEXT_BOTTOMINSTRUCTIONS | IDS_CTRL_STATICTEXT_BOTTOMINSTRUCTIONS
Combo boxes | Combo Box | CTRL_COMBOBOX_01 ... CTRL_COMBOBOX_04 | IDS_CTRL_COMBOBOX_01 ... IDS_CTRL_COMBOBOX_04
Static text | Static Text | CTRL_STATICTEXT_LABEL_01 ... CTRL_STATICTEXT_LABEL_04 | IDS_CTRL_STATICTEXT_LABEL_01 ... IDS_CTRL_STATICTEXT_LABEL_04
Timer | Timer | N/A | N/A


Examples

Combo Boxes Screen

Overview Properties Advanced Examples

These examples show how you can determine which combo box item was selected and other ways of manipulating the combo box control.

Example 1

To try this example, paste the following script onto a default Combo Box screen's On Next event (before the Screen.Next action). This script uses the first default combo box control, CTRL_COMBOBOX_01. The On Next event can be found on the Actions tab of the screen's properties.

strComboText = SessionVar.Expand("%Combo01%");

-- Determine which item was selected and display a dialog message.
if (strComboText == "Item A") then
Dialog.Message("ComboBox", "Item A was selected.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
elseif (strComboText == "Item B") then
Dialog.Message("ComboBox", "Item B was selected.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
elseif (strComboText == "Item C") then
Dialog.Message("ComboBox", "Item C was selected.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
else
Dialog.Message("ComboBox", "No item was selected. The default Item A was chosen.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end

This action script demonstrates how to check which of the three default combo box items were selected when leaving the screen and display a dialog message. This is accomplished by checking the value of the session variable that stores the item text of the selected item.

Example 2

This example requires you to paste code onto two different events on a new Combo Boxes screen.

To try this example, paste the following code onto the On Preload event of a Combo Boxes screen. This event can be found on the Actions tab of the screen's properties.

-- Remove all items from the second combo box control (CTRL_COMBOBOX_02).
DlgComboBox.RemoveItem(CTRL_COMBOBOX_02, -1);

-- Add two default items to the second combo box control.
DlgComboBox.AddItem(CTRL_COMBOBOX_02, "Item A Secondary One");
DlgComboBox.AddItem(CTRL_COMBOBOX_02, "Item A Secondary Two");

-- Select the first item in the second combo box's list.
DlgComboBox.SetProperties(CTRL_COMBOBOX_02, {Selected=1});

This action script first removes all contents from the second combo box control CTRL_COMBOBOX_02. It then adds two items and selects the first item in the list.

You can paste the following code onto the On Ctrl Message event of the same Combo Boxes screen, before the Screen.Next action. This event can be found on the Actions tab of the screen's properties.

-- Check to see if the selection changed message was fired.
if (e_MsgID == MSGID_ONSELCHANGED) then
-- Check to see if the selection change was fired by the CTRL_COMBOBOX_01 control.
if (e_CtrlID == CTRL_COMBOBOX_01) then
-- Remove all items from the CTRL_COMBOBOX_02 control.
DlgComboBox.RemoveItem(CTRL_COMBOBOX_02, -1);

-- Check if "Item A" was selected in the first combo box.
if (e_Details.Text == "Item A") then
-- Add two items to the second combo box control related to "Item A"
DlgComboBox.AddItem(CTRL_COMBOBOX_02, "Item A Secondary One");
DlgComboBox.AddItem(CTRL_COMBOBOX_02, "Item A Secondary Two");
-- Set selected state of the second combo box to the first item in the list.
DlgComboBox.SetProperties(CTRL_COMBOBOX_02, {Selected=1});

-- Check if "Item B" was selected in the first combo box.
elseif (e_Details.Text == "Item B") then
-- Add two items to the second combo box control related to "Item B".
DlgComboBox.AddItem(CTRL_COMBOBOX_02, "Item B Secondary One");
DlgComboBox.AddItem(CTRL_COMBOBOX_02, "Item B Secondary Two");
-- Set selected state of the second combo box to the first item in the list.
DlgComboBox.SetProperties(CTRL_COMBOBOX_02, {Selected=1});

-- Check if "Item C" was selected in the first combo box.
elseif (e_Details.Text == "Item C") then
-- Add two items to the second combo box control related to "Item C".
DlgComboBox.AddItem(CTRL_COMBOBOX_02, "Item C Secondary One");
DlgComboBox.AddItem(CTRL_COMBOBOX_02, "Item C Secondary Two");
-- Set selected state of the second combo box to the first item in the list.
DlgComboBox.SetProperties(CTRL_COMBOBOX_02, {Selected=1});
else
-- Do nothing.
end
end
end

This example illustrates how you can use one combo box to control the contents of a second combo box. When a selection is made in the first combo box CTRL_COMBOBOX_01, the second combo box is populated with items that relate to it. This allows you to create a submenu type design. This action script is run whenever a combo box selection is made on the screen, but reacts when a selection is made in the first combo box.


Overview

Custom Screen

Overview Properties Advanced

The Custom screen is one type of screen available in Setup Factory. It was designed to allow you full control over the number, type, and placement of controls on the screen.

The Custom screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or in the uninstall by choosing Uninstall > Screens... from the program menu and clicking the Add button from the Before Uninstalling or After Uninstalling tabs.

This screen type contains the following two categories of settings:

  • Properties

  • Advanced


Properties

Custom Screen

Overview Properties Advanced

The Custom screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Insert

Add a new control to the current screen. When a control is selected, the mouse pointer turns to cross hairs and the control will be created where you click on the screen. The following controls are available:

Tip: You can also add a control by right-clicking on the screen and selecting Add > <Control Name>.

Billboard

Add a new Billboard control to the current screen. You can edit its properties on the Billboard Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Button

Add a new Button control to the current screen. You can edit its properties on the Button Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Check Box

Add a new Check Box control to the current screen. You can edit its properties on the Check Box Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Combo Box

Add a new Combo Box control to the current screen. You can edit its properties on the Combo Box Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Edit

Add a new Edit Field control to the current screen. You can edit its properties on the Edit Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Group Box

Add a new Group Box control to the current screen. You can edit its properties on the Group Box Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

List Box

Add a new List Box control to the current screen. You can edit its properties on the List Box Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Progress Bar

Add a new Progress Bar control to the current screen. You can edit its properties on the Progress Bar Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Radio Button

Add a new Radio Button control to the current screen. You can edit its properties on the Radio Button Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Scrollable Text

Add a new Scrolling Text control to the current screen. You can edit its properties on the Scrollable Text Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Select Package Tree

Add a new Select Package control to the current screen. You can edit its properties on the Select Package Tree Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Text

Add a new Static Text control to the current screen. You can edit its properties on the Text Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Edit

Opens the selected control's properties dialog so you can edit its settings. You can select a control by either clicking on it on the screen, or selecting its ID from the drop down.

Remove

Remove the selected control from the screen.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Custom screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Custom Screen

Overview Properties Advanced

The following table contains the necessary information to manage and manipulate this screen at runtime.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Tip: All controls on this screen can exceed the defined amount of 32, however Setup Factory's control IDs are only defined up to 32. If you want to add more than 32 of a specific control, you will need to add a numeric value to the control ID's value when you reference it. For example, to access the 33rd button, you would use CTRL_BUTTON_32 + 1, or the 34th, CTRL_BUTTON_32 + 2. String IDs can be referenced by their numbers directly.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Timer | Timer | N/A | N/A
Billboard | Billboard | CTRL_BILLBOARD_01 ... CTRL_BILLBOARD_32 | N/A
Buttons | Button | CTRL_BUTTON_01 ... CTRL_BUTTON_32 | IDS_CTRL_BUTTON_01 ... IDS_CTRL_BUTTON_32
Check Boxes | Check Box | CTRL_CHECK_BOX_01 ... CTRL_CHECK_BOX_32 | IDS_CTRL_CHECK_BOX_01 ... IDS_CTRL_CHECK_BOX_32
Combo Boxes | Combo Box | CTRL_COMBOBOX_01 ... CTRL_COMBOBOX_32 | IDS_CTRL_COMBOBOX_01_DEFAULT ... IDS_CTRL_COMBOBOX_32_DEFAULT IDS_CTRL_COMBOBOX_01_ITEMS ... IDS_CTRL_COMBOBOX_32_ITEMS
Edit Fields | Edit Field | CTRL_EDIT_01 ... CTRL_EDIT_32 | IDS_CTRL_EDIT_01 ... IDS_CTRL_EDIT_32 IDS_CTRL_EDIT_MASK_01 ... IDS_CTRL_EDIT_MASK_32 IDS_CTRL_EDIT_MASK_PLACE_HOLDER_01 ... IDS_CTRL_EDIT_MASK_PLACE_HOLDER_32
Group Boxes | Group Box | CTRL_GROUP_BOX_01 ... CTRL_GROUP_BOX_32 | IDS_CTRL_GROUP_BOX_01 ... IDS_CTRL_GROUP_BOX_32
List Boxes | List Box | CTRL_LIST_BOX_01 ... CTRL_LIST_BOX_32 | IDS_CTRL_LISTBOX_01 ... IDS_CTRL_LISTBOX_32
Progress Bars | Progress Bar | CTRL_PROGRESS_BAR_01 ... CTRL_PROGRESS_BAR_32 | IDS_CTRL_PROGRESS_BAR_01 ... IDS_CTRL_PROGRESS_BAR_32
Radio Buttons | Radio Button | CTRL_RADIO_BUTTON_01 ... CTRL_RADIO_BUTTON_32 | IDS_CTRL_RADIO_BUTTON_01 ... IDS_CTRL_RADIO_BUTTON_32
Scrollable Text | Scrolling Text | CTRL_SCROLLTEXT_BODY_01 ... CTRL_SCROLLTEXT_BODY_32 | IDS_CTRL_SCROLLTEXT_BODY_01 ... IDS_CTRL_SCROLLTEXT_BODY_32 IDS_CTRL_SCROLLTEXT_FILE_01 ... IDS_CTRL_SCROLLTEXT_FILE_32
Select Packages Tree | Select Package | CTRL_SELECT_PACKAGE_TREE_01 ... CTRL_SELECT_PACKAGE_TREE_32 | NIL
Categories | Category | CTRL_CATEGORY_001 ... CTRL_CATEGORY_128 | IDS_CTRL_CATEGORY_NAME_<TREE#>_001 ... IDS_CTRL_CATEGORY_NAME_<TREE#>_128 IDS_CTRL_CATEGORY_DESCRIPTION_<TREE#>_001 ... IDS_CTRL_CATEGORY_DESCRIPTION_<TREE#>_128
Text | Static Text | CTRL_STATICTEXT_LABEL_01 ... CTRL_STATICTEXT_LABEL_32 | IDS_CTRL_STATICTEXT_LABEL_01 ... IDS_CTRL_STATICTEXT_LABEL_32


Overview

Custom Progress Screen

Overview Properties Advanced

The Custom Progress screen is one type of screen available in Setup Factory. It was designed to allow you full control over the number, type, and placement of controls on a progress screen.

This screen type can also be used to show progress during the installation and uninstallation of the files.

The Custom Progress screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or the Change button on the While Installing tab. It can also be used in the uninstall by choosing Uninstall > Screens... from the program menu and clicking the Add button from the Before Uninstalling or After Uninstalling tabs, or Change button on the While Uninstalling tab.

This screen type contains the following two categories of settings:

  • Properties

  • Advanced


Properties

Custom Progress Screen

Overview Properties Advanced

The Custom Progress screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Insert

Add a new control to the current screen. When a control is selected, the mouse pointer turns to cross hairs and the control will be created where you click on the screen. The following controls are available:

Tip: You can also add a control by right-clicking on the screen and selecting Add > <Control Name>.

Billboard

Add a new Billboard control to the current screen. You can edit its properties on the Billboard Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Button

Add a new Button control to the current screen. You can edit its properties on the Button Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Check Box

Add a new Check Box control to the current screen. You can edit its properties on the Check Box Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Combo Box

Add a new Combo Box control to the current screen. You can edit its properties on the Combo Box Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Edit

Add a new Edit Field control to the current screen. You can edit its properties on the Edit Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Group Box

Add a new Group Box control to the current screen. You can edit its properties on the Group Box Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

List Box

Add a new List Box control to the current screen. You can edit its properties on the List Box Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Progress Bar

Add a new Progress Bar control to the current screen. You can edit its properties on the Progress Bar Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Radio Button

Add a new Radio Button control to the current screen. You can edit its properties on the Radio Button Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Scrollable Text

Add a new Scrolling Text control to the current screen. You can edit its properties on the Scrollable Text Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Select Package Tree

Add a new Select Package control to the current screen. You can edit its properties on the Select Package Tree Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Text

Add a new Static Text control to the current screen. You can edit its properties on the Text Properties dialog which can be opened by either clicking the Edit button, or double-clicking the control.

Edit

Opens the selected control's properties dialog so you can edit its settings. You can select a control by either clicking on it on the screen, or selecting its ID from the drop down.

Remove

Remove the selected control from the screen.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Custom Progress screen contains the following screen events:

  • On Preload

  • On Start

  • On Finish

  • On Cancel

  • On Ctrl Message

The "While Installing" or "While Uninstalling" version of the Custom Progress screen has the following events instead:

  • On Preload

  • On Progress

  • On Cancel

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on any of the event names above for a full description.


Advanced

Custom Progress Screen

Overview Properties Advanced

The following table contains the necessary information to manage and manipulate this screen at runtime.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Tip: All controls on this screen can exceed the defined amount of 32, however Setup Factory's control IDs are only defined up to 32. If you want to add more than 32 of a specific control, you will need to add a numeric value to the control ID's value when you reference it. For example, to access the 33rd button, you would use CTRL_BUTTON_32 + 1, or the 34th, CTRL_BUTTON_32 + 2. String IDs can be referenced by their numbers directly.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button (Not available in While Installing or While Uninstalling) | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button (Not available in While Installing or While Uninstalling) | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button (Not available in While Installing or While Uninstalling) | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Timer | Timer | N/A | N/A
Billboard | Billboard | CTRL_BILLBOARD_01 ... CTRL_BILLBOARD_32 | N/A
Buttons | Button | CTRL_BUTTON_01 ... CTRL_BUTTON_32 | IDS_CTRL_BUTTON_01 ... IDS_CTRL_BUTTON_32
Check Boxes | Check Box | CTRL_CHECK_BOX_01 ... CTRL_CHECK_BOX_32 | IDS_CTRL_CHECK_BOX_01 ... IDS_CTRL_CHECK_BOX_32
Combo Boxes | Combo Box | CTRL_COMBOBOX_01 ... CTRL_COMBOBOX_32 | IDS_CTRL_COMBOBOX_01_DEFAULT ... IDS_CTRL_COMBOBOX_32_DEFAULT IDS_CTRL_COMBOBOX_01_ITEMS ... IDS_CTRL_COMBOBOX_32_ITEMS
Edit Fields | Edit Field | CTRL_EDIT_01 ... CTRL_EDIT_32 | IDS_CTRL_EDIT_01 ... IDS_CTRL_EDIT_32 IDS_CTRL_EDIT_MASK_01 ... IDS_CTRL_EDIT_MASK_32 IDS_CTRL_EDIT_MASK_PLACE_HOLDER_01 ... IDS_CTRL_EDIT_MASK_PLACE_HOLDER_32
Group Boxes | Group Box | CTRL_GROUP_BOX_01 ... CTRL_GROUP_BOX_32 | IDS_CTRL_GROUP_BOX_01 ... IDS_CTRL_GROUP_BOX_32
List Boxes | List Box | CTRL_LIST_BOX_01 ... CTRL_LIST_BOX_32 | IDS_CTRL_LISTBOX_01 ... IDS_CTRL_LISTBOX_32
Progress Bars | Progress Bar | CTRL_PROGRESS_BAR_01 ... CTRL_PROGRESS_BAR_32 | IDS_CTRL_PROGRESS_BAR_01 ... IDS_CTRL_PROGRESS_BAR_32
Radio Buttons | Radio Button | CTRL_RADIO_BUTTON_01 ... CTRL_RADIO_BUTTON_32 | IDS_CTRL_RADIO_BUTTON_01 ... IDS_CTRL_RADIO_BUTTON_32
Scrollable Text | Scrolling Text | CTRL_SCROLLTEXT_BODY_01 ... CTRL_SCROLLTEXT_BODY_32 | IDS_CTRL_SCROLLTEXT_BODY_01 ... IDS_CTRL_SCROLLTEXT_BODY_32 IDS_CTRL_SCROLLTEXT_FILE_01 ... IDS_CTRL_SCROLLTEXT_FILE_32
Select Packages Tree | Select Package | CTRL_SELECT_PACKAGE_TREE_01 ... CTRL_SELECT_PACKAGE_TREE_32 | NIL
Categories | Category | CTRL_CATEGORY_001 ... CTRL_CATEGORY_128 | IDS_CTRL_CATEGORY_NAME_<TREE#>_001 ... IDS_CTRL_CATEGORY_NAME_<TREE#>_128 IDS_CTRL_CATEGORY_DESCRIPTION_<TREE#>_001 ... IDS_CTRL_CATEGORY_DESCRIPTION_<TREE#>_128
Text | Static Text | CTRL_STATICTEXT_LABEL_01 ... CTRL_STATICTEXT_LABEL_32 | IDS_CTRL_STATICTEXT_LABEL_01 ... IDS_CTRL_STATICTEXT_LABEL_32


Overview

Edit Fields Screen

Overview Properties Advanced Examples

The Edit Fields screen is one type of screen available in Setup Factory. It was designed to allow you to present both static text and edit fields that can be used to gather information from the user. The maximum number of edit fields that can be added on this screen is 32 (without a banner or heading/label text). The layout would be 8 rows containing 4 edit fields. With normal banner styles and heading text, 4 rows is visibly the ideal amount.

This screen type is used for various pre-made screens available in Setup Factory, one of which is the User Information screen.

The Edit Fields screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or on the Before Uninstalling or After Uninstalling tabs in the uninstall section.

This screen type contains the following two categories of settings and some examples:

  • Properties

  • Advanced

  • Examples


Properties

Edit Fields Screen

Overview Properties Advanced Examples

The Edit Field screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Top:

The text you want to appear at the top of the screen, above all of the edit fields.

Bottom:

The text you want to appear at the bottom of the screen, below all of the edit fields.

Edit Fields

ID

The control IDs of each edit field on the current screen.

Label

The text label of each edit field on the current screen.

Note: Using the ampersand character (&) in a label's text will make the character to its right a mnemonic key for the control.

Session Variable

The unique session variable that each edit field's value will be stored in at runtime.

Add

Opens the Edit Field Properties dialog where you can add a new edit field to the current screen.

Remove

Remove the currently selected edit field from the screen.

Edit

Opens the Edit Field Properties dialog where you can edit the properties of the currently selected edit field.

Up ( )

Move the selected edit field up one position in the edit field list.

Down ( )

Move the selected edit field down one position in the edit field list.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The edit fields screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Edit Fields Screen

Overview Properties Advanced Examples

The following table contains the necessary information to manage and manipulate this screen at run time:

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Instructions (bottom) | Static Text | CTRL_STATICTEXT_BOTTOMINSTRUCTIONS | IDS_CTRL_STATICTEXT_BOTTOMINSTRUCTIONS
Edit field labels | Static Text | CTRL_STATICTEXT_LABEL_01 ... CTRL_STATICTEXT_LABEL_32 | IDS_CTRL_STATICTEXT_LABEL_01 ... IDS_CTRL_STATICTEXT_LABEL_32
Edit fields | Edit Field | CTRL_EDIT_01 ... CTRL_EDIT_32 | IDS_CTRL_EDIT_01 ... IDS_CTRL_EDIT_32
Edit field browse buttons | Button | CTRL_BUTTON_01 ... CTRL_BUTTON_32 | IDS_CTRL_BUTTON_01 ... IDS_CTRL_BUTTON_32
Timer | Timer | N/A | N/A


Examples

Edit Fields Screen

Overview Properties Advanced Examples

These examples show how you can retrieve the contents of an edit field control from a default Edit Fields screen.

Example 1

To try this example, paste the following code onto the On Next event (before the Screen.Next action) of an Edit Fields screen. This event can be found on the Actions tab of the screen's properties.

-- Create an output string containing the text within the first edit field with the session variable %EditVar01%.
strOutputString1 = "The text in the first edit field is: "..SessionVar.Expand("%EditVar01%");

-- Create an output string containing the text within the second edit field with the session variable %EditVar02%.
strOutputString2 = "The text in the second edit field is: "..SessionVar.Expand("%EditVar02%");

-- Create an output string containing the text within the third edit field with the session variable %EditVar03%.
strOutputString3 = "The text in the third edit field is: "..SessionVar.Expand("%EditVar03%");

-- Display a dialog containing the four output strings displaying the values in each edit field.
Dialog.Message("Edit Fields", strOutputString1.."\r\n"..strOutputString2.."\r\n"..strOutputString3, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);

This action script demonstrates how to retrieve the text entered in an edit field, in this case, simply outputting it as a dialog message when you click the Next button.

Example 2

To try this example, paste the following code onto the On Next event of an Edit Fields screen and remove the Screen.Next() action that is there by default. This event can be found on the Actions tab of the screen's properties.

-- Check to make sure the first two edit fields are not empty.
if (SessionVar.Expand("%EditVar01%") == "") then
-- Display a dialog notifying the user that the first edit field cannot be empty.
Dialog.Message("Notice", "The first edit field cannot be empty. Please enter a value.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
-- Set the input focus to the first edit field.
Screen.SetFocus(CTRL_EDIT_01);
elseif (SessionVar.Expand("%EditVar02%") == "") then
-- Display a dialog notifying the user that the second edit field cannot be empty.
Dialog.Message("Notice", "The second edit field cannot be empty. Please enter a value.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
-- Set the input focus to the second edit field.
Screen.SetFocus(CTRL_EDIT_02);
else
-- advance to the next screen
Screen.Next();
end

This action script example illustrates how you can validate the contents of an edit field before proceeding in the install. The above script checks to make sure the first two edit fields on the screen are not empty, and prompts the user for input if they are. As you can see, other types of validation can easily be performed using this type of design.


Overview

License Agreement Screen

Overview Properties Advanced

The License Agreement screen is one type of screen available in Setup Factory. It was designed to allow you to display your application's license agreement text that the user must read, and agree to, in order to proceed with the installation. The license text can either be in plain ASCII, or HTML format and can be specified during the design phase, or read in from a file at run time.

The License Agreement screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or in the uninstall section from the Before Uninstalling or After Uninstalling tabs.

This screen type contains the following two categories of settings:

  • Properties

  • Advanced


Properties

License Agreement Screen

Overview Properties Advanced

The License Agreement screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Screen Text

Load from file

Load the license agreement text from a file at runtime. You can click the browse button ( [image] ) to select a file from your system. This file will automatically be included as a resource in your install.

Note: The maximum file size allowed is 10mb

Note: If you are referencing an external file that is not local using a session variable or hard-coded path, you must use the HTML text type.

Specify now

Specify the text now either by directly typing it in, pasting the text, or importing it from a file.

Plain text

Display the license agreement as plain ASCII text.

Note: If you are loading an external file that is not local, you must use the HTML text type instead.

HTML

Display the license agreement as HTML text.

Import

Select a file from your system that you want to import immediately.

Options

Agree text:

The text you want to appear to the right of the "I agree" radio button.

Note: Using the ampersand character (&) in the agree text will make the character to its right a mnemonic key for the control.

Disagree text:

The text you want to appear to the right of the "I disagree" radio button.

Note: Using the ampersand character (&) in the disagree text will make the character to its right a mnemonic key for the control.

Default:

The radio button you want selected by default.

Agree

Select the "I agree" radio button when the screen is displayed.

Disagree

Select the "I disagree" radio button when the screen is displayed.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The License Agreement screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

License Agreement Screen

Overview Properties Advanced

The following table contains the necessary information to manage and manipulate this screen at run time.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
License agreement text | Scrolling Text | CTRL_SCROLLTEXT_BODY | IDS_CTRL_SCROLLTEXT_BODY
I agree button | Radio Button | CTRL_RADIOBTN_AGREE | IDS_CTRL_RADIOBTN_AGREE
I disagree button | Radio Button | CTRL_RADIOBTN_DISAGREE | IDS_CTRL_RADIOBTN_DISAGREE
Timer | Timer | N/A | N/A


Overview

List Box Screen

Overview Properties Advanced Examples

The List Box screen is another type of screen designed for user selection. A list box is a control that contains a scrollable list of textual options that can be selected by the user. This screen contains two list box styles, a standard list box and a checklist box. A checklist box has the addition of a check box for each list box item. Other features on this screen include multiple selection and alphabetic item sorting.

The List Box screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or in the uninstall section on the Before Uninstalling or After Uninstalling tabs.

This screen type contains the following two categories of settings and some examples:

  • Properties

  • Advanced

  • Examples


Properties

List Box Screen

Overview Properties Advanced Examples

The List Box screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Top:

The text you want to appear at the top of the screen, above the list box.

Bottom:

The text you want to appear at the bottom of the screen, below the list box.

List Box

Items:

The items you want to show in the list box. Each line in this area will be shown as one list box item.

Options

Enabled

Enable the list box so it responds to user interaction. When a list box is disabled, all of its items will appear greyed out and cannot be selected.

Visible

Set the initial visibility of the list box (whether it's visible when the screen is displayed).

Sorted

Sort the list box items alphabetically at run time. If this option is unchecked, list box items will be displayed in the order they appear at design time or added at run time.

Multi select

Enable multiple list box items to be selected at one time.

Style

List Box

Use a standard list box style.

Checklist Box

Use a checklist box style. A checklist box is a standard list box combined with a check box for each item.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The List Box screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

List Box Screen

Overview Properties Advanced Examples

The following table contains the necessary information to manage and manipulate this screen at run time.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Instructions (bottom) | Static Text | CTRL_STATICTEXT_BOTTOMINSTRUCTIONS | IDS_CTRL_STATICTEXT_BOTTOMINSTRUCTIONS
List box | List Box | CTRL_LIST_BOX | IDS_CTRL_LISTBOX
Timer | Timer | N/A | N/A


Examples

List Box Screen

Overview Properties Advanced Examples

These examples show how you can retrieve and manipulate the contents of a list box control from a default List Boxes screen.

Example 1

To try this example, paste the following code onto the On Next event in between the else and the Screen.Next action. This event can be found on the Actions tab of the screen's properties.

-- Retrieve the table with all of the selected list box items.
tbSelected = DlgListBox.GetSelected(CTRL_LIST_BOX);

strSelectedLabels = "";

-- Loop through the table tbSelected and add the name and index of the selected item to a string.
for index, value in pairs(tbSelected) do
-- Get the properties of the selected listbox item, so you can retrieve its name.
tbProperties = DlgListBox.GetItemProperties(CTRL_LIST_BOX, value);

-- Add the name of the listbox item (tbProperties.Text) and its index to the string for outputting.
strSelectedLabels = "Index: "..value.." - "..strSelectedLabels..tbProperties.Text.."\r\n";
end

-- Display the labels and indexes of all selected listbox items in a dialog message.
Dialog.Message("ListBox", "The following listbox items were selected:\r\n"..strSelectedLabels, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);

This action script demonstrates how to retrieve the items that were selected in a list box, in this case, simply outputting its indexes and values as a dialog message when you click the Next button.

Example 2

This example requires you to paste code onto two different events on a new List Box screen.

To try this example, paste the following code onto the On Preload event of a List Box screen. This event can be found on the Actions tab of the screen's properties.

-- Remove all items from the list box.
DlgListBox.DeleteItem(CTRL_LIST_BOX, -1);

-- Add a new item called "Item One" to the list box.
DlgListBox.AddItem(CTRL_LIST_BOX, "Item One");
-- Set the associated data of "Item One" to _TempLaunchFolder\\MyProgOne.exe.
DlgListBox.SetItemProperties(CTRL_LIST_BOX, 1, {ItemData=_TempLaunchFolder.."\\MyProgOne.exe"});

-- Add a new item called "Item Two" to the list box.
DlgListBox.AddItem(CTRL_LIST_BOX, "Item Two");
-- Set the associated data of "Item Two" to "C\\MyProgTwo.exe".
DlgListBox.SetItemProperties(CTRL_LIST_BOX, 2, {ItemData="C\\MyProgTwo.exe"});

-- Add a new item called "Item Three" to the list box.
DlgListBox.AddItem(CTRL_LIST_BOX, "Item Three");
-- Set the associated data of "Item Three" to the string "This is the item three data".
DlgListBox.SetItemProperties(CTRL_LIST_BOX, 3, {ItemData="This is the item three data"});

This action script first removes all contents from the list box control. It then adds three new items and sets each of their associated data items.

You can paste the following code onto the On Next event, in between the else and the Screen.Next action. This event can be found on the Actions tab of the screen's properties.

-- Retrieve the table with all of the selected listbox items.
tbSelected = DlgListBox.GetSelected(CTRL_LIST_BOX);

strSelectedLabels = "";
-- Loop through the table tbSelected and add the name, index and associated data of the selected item to a string.
for index, value in pairs(tbSelected) do
-- Get the properties of the selected listbox item, so you can retrieve its name.
tbProperties = DlgListBox.GetItemProperties(CTRL_LIST_BOX, value);
-- Add the name of the listbox item (tbProperties.Text) and its index to the string for outputting.
strSelectedLabels = strSelectedLabels.."Index: "..value.."\r\n".."Text: "..tbProperties.Text.."\r\n".."Associated Data: "..tbProperties.ItemData.."\r\n\r\n";
end

-- Display the labels and indexes of all selected listbox items in a dialog message.
Dialog.Message("ListBox", "The following listbox items were selected:\r\n"..strSelectedLabels, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);

This action script example is very similar to Example 1, however in this case, the item's associated data that was set on the On Preload event is also shown in the dialog message when you click the Next button.


Overview

Progress Bars Screen

Overview Properties Advanced Examples

The Progress Bars screen is one type of screen available in Setup Factory. It was designed to provide a visual representation of progress for various tasks during the installation. This screen is useful in situations where large amounts of script need to be executed, or for actions that may take longer to complete, such as a file download or file copy. The progress bars screen can be configured to show one, two or no progress meters.

This screen type is also used to show progress during the installation and uninstallation of the files.

The Progress Bars screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or in the uninstall section from the Before Uninstalling or After Uninstalling tabs.

This screen type contains the following two categories of settings and some examples:

  • Properties

  • Advanced

  • Examples


Properties

Progress Bars Screen

Overview Properties Advanced Examples

The Progress Bars screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Text:

The description text you want to display in the body of the screen.

Progress Bar One

Show progress prompt one

Show a prompt above the first progress meter's status text.

Prompt:

The text you want to use as a prompt for the first progress meter.

Note: Using the ampersand character (&) in the prompt's text will make the character to its right a mnemonic key for the control.

Show status text one

Show the status text for the first progress meter.

Status text:

The status text you want to display for the first progress meter. This text will appear directly above the first progress meter.

Note: Using the ampersand character (&) in the status text will make the character to its right a mnemonic key for the control.

Show progress bar one

Show the first progress meter.

Note: If the screen's theme does not use custom colors, the progress bar has XP style turned on, and the operating system is Windows XP or newer (it uses themes) then Setup Factory will use the current Windows theme when drawing the progress bar. This means that the progress bar will ignore the Segmented or Smooth settings below and will be smooth or segmented depending on the available Windows Theme.

Progress text:

The text you want to appear inside the first progress meter.

Segmented

Use segmented bars to represent progress.

Smooth

Use a solid bar to represent progress.

XP style

Use an XP style progress meter.

Progress Bar Two

Show progress prompt two

Show a prompt above the second progress meter's status text.

Prompt:

The text you want to use as a prompt for the second progress meter.

Note: Using the ampersand character (&) in the prompt's text will make the character to its right a mnemonic key for the control.

Show status text two

Show the status text for the second progress meter.

Status text:

The status text you want to display for the second progress meter. This text will appear directly above the second progress meter.

Note: Using the ampersand character (&) in the status text will make the character to its right a mnemonic key for the control.

Show progress bar two

Show the second progress meter.

Note: If the screen's theme does not use custom colors, the progress bar has XP style turned on, and the operating system is Windows XP or newer (it uses themes) then Setup Factory will use the current Windows theme when drawing the progress bar. This means that the progress bar will ignore the Segmented or Smooth settings below and will be smooth or segmented depending on the available Windows Theme.

Progress text:

The text you want to appear inside the second progress meter.

Segmented

Use segmented bars to represent progress.

Smooth

Use a solid bar to represent progress.

XP Style

Use an XP style progress meter.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button, however there will be no visual progress available at that point.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Progress Bars screen contains the following screen events:

  • On Preload

  • On Start

  • On Finish

  • On Cancel

The "While Installing" version of the Progress Bars screen has the following events instead:

  • On Preload

  • On Progress

  • On Cancel

Tip: See the Advanced topic for the list of string IDs that are available on this screen.

Tip: You can click on any of the event names above for a full description.


Advanced

Progress Bars Screen

Overview Properties Advanced Examples

The following table contains the necessary information to manage and manipulate this screen at runtime.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Progress prompt one | Static Text | CTRL_STATICTEXT_LABEL_01 | IDS_CTRL_STATICTEXT_LABEL_01
Status text one | Static Text | CTRL_STATICTEXT_LABEL_02 | IDS_CTRL_STATICTEXT_LABEL_02
Progress bar one | Progress Bar | CTRL_PROGRESS_BAR_01 | IDS_CTRL_PROGRESS_BAR_01
Progress prompt two | Static Text | CTRL_STATICTEXT_LABEL_03 | IDS_CTRL_STATICTEXT_LABEL_03
Status text two | Static Text | CTRL_STATICTEXT_LABEL_04 | IDS_CTRL_STATICTEXT_LABEL_04
Progress bar two | Progress Bar | CTRL_PROGRESS_BAR_02 | IDS_CTRL_PROGRESS_BAR_02
Timer | Timer | N/A | N/A


Examples

Progress Bars Screen

Overview Properties Advanced Examples

This example shows how you can use the Progress Bars screen to show progress for a file download that may take a long time to complete.

Example 1

This example requires you to paste code onto three different action events on a Progress Bars screen. In order to test this example, you also need to have a file available for download.

To try this example, paste the following code onto the On Preload event of a Progress Bars screen. This event can be found on the Actions tab of the screen's properties.

-- Set some variables for the file download...
-- Put your full URL to the file here...
strSourceURL = "http://www.yoursite.com/myfile.zip";

-- Put the destination path and filename here...
strDestinationFile = _TempFolder.."\\myfile.zip";
bIsBinaryFile = true;

-- Set to true if the user presses cancel (see the On Cancel event)
bCancelled = false;

-- Initialize the progress bar...
DlgProgressBar.SetRange(CTRL_PROGRESS_BAR_01,0,100);
DlgProgressBar.SetPos(CTRL_PROGRESS_BAR_01,0);

This action script sets some variables that are required for the rest of the screen's action script. You must make some modifications to its script such as the file's source and destination.

Paste the following code onto the On Start event of the Progress Bars screen. This event can be found on the Actions tab of the screen's properties.

-- Initialize some display variables...
local strLocalFileName = strDestinationFile;
local tblFileParts = String.SplitPath(strDestinationFile);

if(tblFileParts)then
strLocalFileName = tblFileParts.Filename..tblFileParts.Extension;
end

local strWebSiteName = strSourceURL;
local nPosition = String.Find(strSourceURL,"://");
if(nPosition ~= -1)then
local nPositionNextSlash = String.Find(strSourceURL,"/",nPosition+3);
if(nPositionNextSlash ~= -1)then
strWebSiteName = String.Mid(strSourceURL,nPosition+3,(nPositionNextSlash-nPosition-3));
end
end

-- The callback function - used to display the download progress
function fcnDownloadCallback(BytesRead,FileSize,TransferRate,SecondsLeft,SecondsLeftFormat,Message)
if(bCancelled)then
-- Abort the download...
return false;
end

DlgStaticText.SetProperties(CTRL_STATICTEXT_LABEL_01,{Text="Downloading: "..strLocalFileName.." from "..strWebSiteName});

local nPctComplete = 0;
if(FileSize > 0)then
nPctComplete = (BytesRead/FileSize) * 100;
end

DlgProgressBar.SetPos(CTRL_PROGRESS_BAR_01,nPctComplete);

local strStatusText = "";
if(Message ~= "")then
strStatusText = Message;
else
-- It is downloading...
local strXferRate = string.format("%.2f",TransferRate);
strStatusText = "Estimated time left: "..SecondsLeftFormat.." - Transfer Rate: "..strXferRate.." KB/Sec";
end

DlgStaticText.SetProperties(CTRL_STATICTEXT_LABEL_02,{Text=strStatusText});

return true;
end

local nTransferType = MODE_TEXT;
if(bIsBinaryFile)then
nTransferType = MODE_BINARY;
end

-- The actual download action...
HTTP.Download(strSourceURL,strDestinationFile,nTransferType,20,80,nil,nil,fcnDownloadCallback);
local nLastError = Application.GetLastError();
if(nLastError ~= 0)then
Dialog.Message("Download Failed",_tblErrorMessages[nLastError]);
end

This action script uses the HTTP.Download action to download a file and displays its progress using the Progress Bars screen. The action's visible progress and status is handled by the callback function fcnDownloadCallback containing actions such as DlgProgressBar.SetPos

Paste the following code onto the On Cancel event of the Progress Bars screen. This event can be found on the Actions tab of the screen's properties.

local nResult = Dialog.Message("Confirm","Are you sure that you want to abort the download?",MB_YESNO,MB_ICONQUESTION);
if(nResult == IDYES)then
bCancelled = true;
end

This action script handles the case where the user pressed the Cancel button on the screen. If this occurs, a dialog message will be shown and the action will be cancelled if the user presses "Yes".


Overview

Radio Buttons Screen

Overview Properties Advanced Examples

The Radio Buttons screen is one type of screen available in Setup Factory that was designed to allow you to present a user selection interface via radio buttons. The maximum number of radio buttons that can be added on this screen is 32 with a maximum horizontal layout of 4 columns.

The Radio Buttons screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or in the uninstall section from the Before Uninstalling or After Uninstalling tabs.

This screen type contains the following two categories of settings and some examples:

  • Properties

  • Advanced

  • Examples


Properties

Radio Buttons Screen

Overview Properties Advanced Examples

The Radio Buttons screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Top:

The text you want to appear at the top of the screen, above all of the radio buttons.

Bottom:

The text you want to appear at the bottom of the screen, below all of the radio buttons.

Radio Buttons

ID

The control IDs of each radio button on the current screen.

Label

The text label of each radio button on the current screen.

Note: Using the ampersand character (&) in the label text will make the character to its right a mnemonic key for the control.

Add ( )

Opens the Radio Button Properties dialog where you can add a new radio button to the current screen.

Remove ( )

Remove the currently selected radio button from the screen.

Edit ( )

Opens the Radio Button Properties dialog where you can edit the properties of the currently selected radio button.

Up ( )

Move the selected radio button up one position in the radio button list.

Down ( )

Move the selected radio button down one position in the radio button list.

Options

Number of columns:

The number of radio button columns you want to show. The maximum number of columns is 4.

Distribute:

The layout you want to have for the radio buttons. Choose from:

Vertical

Distribute the radio buttons vertically from top to bottom.

Horizontal

Distribute the radio buttons horizontally from left to right.

Default selection

The radio button you want selected by default.

Store result in session variable:

The session variable you want to store the selected radio button control ID in.

Tip: If you plan to use the session variable in a conditional statement containing a comparison with the control ID, you first need to expand the session variable using the SessionVar.Expand action, and then convert the result to a number using the String.ToNumber action.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Radio Buttons screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Radio Buttons Screen

Overview Properties Advanced Examples

The following table contains the necessary information to manage and manipulate this screen at run time.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Instructions (bottom) | Static Text | CTRL_STATICTEXT_BOTTOMINSTRUCTIONS | IDS_CTRL_STATICTEXT_BOTTOMINSTRUCTIONS
Radio buttons | Radio Button | CTRL_RADIO_BUTTON_01 ... CTRL_RADIO_BUTTON_32 | IDS_CTRL_RADIO_BUTTON_01 ... IDS_CTRL_RADIO_BUTTON_32
Timer | Timer | N/A | N/A


Examples

Radio Buttons Screen

Overview Properties Advanced Examples

This example shows how you can detect which radio button was selected from a default Radio Buttons screen.

To try this example, paste the following code onto the On Next event (before the Screen.Next action) of a Radio Buttons screen. This event can be found on the Actions tab of the screen's properties.

-- Convert the selected radio button control to a number for the comparison.
nSelectedControl = String.ToNumber(SessionVar.Expand("%RadioSelection%"));

-- Check to see which radio button was selected by comparing the selected radio button and each raido button control ID.
if (nSelectedControl == CTRL_RADIO_BUTTON_01) then
Dialog.Message("Radio Buttons", "The first radio button was selected.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
elseif (nSelectedControl == CTRL_RADIO_BUTTON_02) then
Dialog.Message("Radio Buttons", "The second radio button was selected.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
elseif (nSelectedControl == CTRL_RADIO_BUTTON_03) then
Dialog.Message("Radio Buttons", "The third radio button was selected.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
elseif (nSelectedControl == CTRL_RADIO_BUTTON_04) then
Dialog.Message("Radio Buttons", "The fourth radio button was selected.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end

This action script demonstrates how to determine which radio button was selected on a Radio Buttons screen. In this example, a dialog message is shown when you click the Next button.


Overview

Scrolling Text Screen

Overview Properties Advanced

The Scrolling Text screen is one type of screen available in Setup Factory. It was designed to allow you to display large amounts of text that can be viewed through a scrollable window. The body text can either be in plain ASCII, or HTML format and can be specified during the design phase, or read in from a file at run time.

This screen type is used for various pre-made screens available in Setup Factory. These include the Scrolling HTML and the Web Site screen.

The Scrolling Text screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or from the Before Uninstalling or After Uninstalling in the uninstall section.

This screen type contains the following two categories of settings:

  • Properties

  • Advanced


Properties

Scrolling Text Screen

Overview Properties Advanced

The Scrolling Text screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Text Type

Plain text

Display the text in plain ASCII format.

Note: If you are loading a file that is not local, you must use the HTML text type instead.

HTML

Display the text in HTML format.

Screen Text

Load from file

Load the text from a file at runtime. You can click the browse button ( [image] ) to select a file from your system. This file will automatically be included as a resource in your install.

Note: If you are referencing an external file that is not local using a session variable or hard-coded path, you must use the HTML text type.

Note: Each language contains its own "Load from file" value. This means you can load a different file to be displayed on the screen for each language configured in your project.

Specify now

Specify the screen text now either by directly typing it in, pasting the text, or importing it from a file.

Import

Select a file from your system that you want to import immediately.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Scrolling Text screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Scrolling Text Screen

Overview Properties Advanced

The following table contains the necessary information to manage and manipulate this screen at runtime.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Body text | Scrolling Text | CTRL_SCROLLTEXT_BODY | IDS_CTRL_SCROLLTEXT_BODY
Timer | Timer | N/A | N/A


Overview

Scrolling Text Progress Screen

Overview Properties Advanced

The Scrolling Text Progress screen is one type of screen available in Setup Factory that was designed to allow you to display progress via lines of text. Text can be added to this screen's scrollable window using DlgScrollingText actions.

The Scrolling Text Progress screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or the Before Uninstalling or After Uninstalling in the uninstall section.

This screen type contains the following two categories of settings:

  • Properties

  • Advanced


Properties

Scrolling Text Progress Screen

Overview Properties Advanced

The Scrolling Text Progress screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Top:

The text you want to appear above the scrolling text progress area.

Bottom:

The text you want to appear below the scrolling text progress area.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Scrolling Text Progress screen contains the following screen events:

  • On Preload

  • On Start

  • On Finish

  • On Cancel

The "While Installing" version of the Scrolling Text Progress screen has the following events instead:

  • On Preload

  • On Progress

  • On Cancel

Tip: See the Advanced topic for the list of string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Scrolling Text Progress Screen

Overview Properties Advanced

The following table contains the necessary information to manage and manipulate this screen at runtime.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Instructions (bottom) | Static Text | CTRL_STATICTEXT_BOTTOMINSTRUCTIONS | IDS_CTRL_STATICTEXT_BOTTOMINSTRUCTIONS
Scrolling text | Scrolling Text | CTRL_SCROLLTEXT_BODY | IDS_CTRL_SCROLLTEXT_BODY
Timer | Timer | N/A | N/A


Overview

Select Install Folder Screen

Overview Properties Advanced

The Select Install Folder screen is one type of screen available in Setup Factory. It was designed to allow the user to select a folder on their system, usually the destination for the installation's files. Other available features on this screen include the automatic calculation of required and available disk space for the install.

The Select Install Folder screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or from the Before Uninstalling or After Uninstalling tabs in the uninstall section.

This screen type contains the following two categories of settings:

  • Properties

  • Advanced


Properties

Select Install Folder Screen

Overview Properties Advanced

The Select Install Folder screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Text:

The instruction text you want to appear in the body of the screen.

Space Requirements

Show space required

Automatically calculate and display the amount of disk space the installation requires.

Text:

The text that you want to display with the amount of space that the current installation configuration requires. Usually this should be something like "Space required on drive: %SpaceRequired%".

Note: The session variable %SpaceRequired% is used on this screen to store the required space value. This variable must exist in this text for the calculated value to be shown.

Note: Using the ampersand character (&) in the text will make the character to its right a mnemonic key for the control.

Show space available

Automatically calculate and display the amount of free disk space the user has on the current drive.

Text:

The text that you want to display with the amount of free space the user has on the their system. Usually this should be something like "Space available on selected drive: %SpaceAvailable%".

Note: The session variable %SpaceAvailable% is used on this screen to store the space available value. This variable must exist in this text for the calculated value to be shown.

Note: Using the ampersand character (&) in the text will make the character to its right a mnemonic key for the control.

Install Folder

Prompt:

The text that you want to display directly above the install folder field.

Note: Using the ampersand character (&) in a prompt's text will make the character to its right a mnemonic key for the control.

Default folder:

The default text that you want to appear in the install folder field. In general this should be the session variable %AppFolder%.

Store result in session variable:

The custom session variable you want to use to store the text in the edit field. In general this should be the built-in session variable %AppFolder%.

Enabled

Enable the install folder field so it responds to user interaction. When the edit field is disabled, it will appear greyed out and cannot be edited by the user.

Browse Button

Text:

The text you want to display on the folder browse button.

Note: Using the ampersand character (&) in a button's text will make the character to its right a mnemonic key for the control.

Enabled

Enable the browse button. If unchecked, the browse button will be disabled.

Visible

Set the initial visibility of the browse button (whether it's visible when the screen is displayed).

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Select Install Folder screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Select Install Folder Screen

Overview Properties Advanced

The following table contains the necessary information to manage and manipulate this screen at runtime.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Install folder prompt | Static Text | CTRL_STATICTEXT_LABEL_01 | IDS_CTRL_STATICTEXT_LABEL_01
Install folder edit | Edit Field | CTRL_EDIT_FOLDER | IDS_CTRL_EDIT_FOLDER
Install folder browse | Button | CTRL_BUTTON_BROWSE | IDS_CTRL_BUTTON_BROWSE
Space required by setup | Static Text | CTRL_STATICTEXT_SPACEREQUIRED | IDS_CTRL_STATICTEXT_SPACEREQUIRED
Space available on drive | Static Text | CTRL_STATICTEXT_SPACEAVAILABLE | IDS_CTRL_STATICTEXT_SPACEAVAILABLE
Timer | Timer | N/A | N/A


Overview

Select Packages Screen

Overview Properties Advanced

Many products contain different types of installs which offer various optional components that can be chosen by the user. The Select Packages screen is one type of screen available in Setup Factory that was designed to work with this type of design. This screen allows you to display a Windows tree structure of available packages that are grouped into categories. A package contains a group of files, while a category contains a group of packages and/or other categories. Selections of packages or categories are represented by check boxes.

Other available features on this screen include the automatic calculation of required and available disk space for the install based on the package selection, as well as description text for both packages and categories.

The Select Packages screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or from the Before Uninstalling or After Uninstalling in the uninstall section.

This screen type contains the following two categories of settings:

  • Properties

  • Advanced


Properties

Select Packages Screen

Overview Properties Advanced

The Select Packages screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Instructions

Text:

The instruction text you want to appear in the body of the screen above the package tree.

Show total size

Automatically calculate and display the amount of disk space the installation requires along with a text description.

Note: By default the text used is "Space required by setup: %SpaceRequired%". The session variable %SpaceRequired% is a custom session variable on this screen where the required space value is stored.

Show package descriptions

Show the package descriptions for each package that is selected at runtime. The description text will appear in the area to the right of the package tree.

Select Packages

Tree:

A tree structure consisting of categories and packages. A category is a selectable group of packages that when chosen, selects all of the contents within it. Categories can contain packages as well as other categories.

Add ( )

Open the Category Properties dialog where you can create a new package category.

Remove ( )

Remove the selected category or package from the package tree.

Edit ( )

Open the Category Properties dialog if a category is currently selected, or the Package Properties dialog if a package is currently selected, where you can edit their properties.

Up ( )

Move the selected category or package up one position in the package tree.

Down ( )

Move the selected category or package down one position in the package tree.

Right ( )

Move the selected category or package right one position in the package tree. This means that the selected item will be moved down one position in the tree structure.

Left ( )

Move the selected category or package left one position in the package tree. This means that the selected item will be moved up one position in the tree structure.

Packages:

A list of all the current packages defined in the setup, defined by their package IDs.

Add Package ( )

Add the selected package to the package tree.

Remove Package ( )

Remove the selected package from the package tree.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Select Packages screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: you can determine which category has been selected using the DlgSelectPackages.GetCategoryProperties action. You can also determine the states of individual packages using the SetupData.GetPackageProperties action.

Tip: You can click on one of the event names above for a full description.


Advanced

Select Packages Screen

Overview Properties Advanced

The following table contains the necessary information to manage and manipulate this screen at runtime.

Tip: you can determine which category has been selected using the DlgSelectPackages.GetCategoryProperties action. You can also determine the states of individual packages using the SetupData.GetPackageProperties action.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Package descriptions | Static Text | CTRL_STATICTEXT_BODY | IDS_CTRL_STATICTEXT_BODY
Space required text | Static Text | CTRL_STATICTEXT_SPACEREQUIRED | IDS_CTRL_STATICTEXT_SPACEREQUIRED
Select package tree | Select Package | CTRL_SELECT_PACKAGE_TREE | NIL
Categories | Category | CTRL_CATEGORY_001 ... CTRL_CATEGORY_128 | IDS_CTRL_CATEGORY_001 ... IDS_CTRL_CATEGORY_128
Timer | Timer | N/A | N/A


Overview

Select Shortcut Folder Screen

Overview Properties Advanced

The Select Shortcut Folder screen is one type of screen available in Setup Factory. It was designed to provide the user with the ability to select which folder they would like their program shortcuts created in. This screen also offers the option of providing your users with choice of which user profile ("per user" or "all user") they would like their shortcuts to be created in.

The Select Shortcut Folder screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs or from the Before Uninstalling or After Uninstalling tabs in the uninstalll section.

This screen type contains the following two categories of settings:

  • Properties

  • Advanced


Properties

Select Shortcut Folder Screen

Overview Properties Advanced

The Select Shortcut Folder screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Static

Text:

The instruction text you want to display on the screen.

Shortcut Folder

Prompt above the shortcut folder field:

The text you want to display above the shortcut folder field.

Note: Using the ampersand character (&) in the prompt text will make the character to its right a mnemonic key for the control.

Default shortcut folder:

The default shortcut folder text you want to initially display in the shortcut folder field. This will usually be the session variable %AppShortcutFolderName%.

Enabled

Enable the shortcut folder field so it responds to user interaction. When the shortcut folder is disabled, the combo box cannot be accessed or modified.

Session Variables

Store folder name in:

The session variable that you want to store the selected shortcut folder name in. Normally this variable is %AppShortcutFolderName%.

Profile

Show profile selection radio buttons

Allow the user to choose which user profile they would like to create their shortcuts in. If unchecked, the default user profile defined in Project Settings will be used when creating shortcuts.

Per-user prompt:

The text that you want to display to the right of the "Per user" radio button.

Note: Using the ampersand character (&) in the prompt text will make the character to its right a mnemonic key for the control.

All-user prompt:

The text that you want to display to the right of the "All user" radio button.

Note: Using the ampersand character (&) in the prompt text will make the character to its right a mnemonic key for the control.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Select Shortcut Folder screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Select Shortcut Folder Screen

Overview Properties Advanced

The following table contains the necessary information to manage and manipulate this screen at runtime.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Instructions (top) | Static Text | CTRL_STATICTEXT_TOPINSTRUCTIONS | IDS_CTRL_STATICTEXT_TOPINSTRUCTIONS
Shortcut folder prompt | Static Text | CTRL_STATICTEXT_LABEL_01 | IDS_CTRL_STATICTEXT_LABEL_01
Shortcut folder | Combo Box | CTRL_COMBOBOX_SHORTCUTFOLDERS | IDS_CTRL_COMBOBOX_SHORTCUTFOLDERS
Per user profile | Radio Button | CTRL_RADIOBTN_PERUSER | IDS_CTRL_RADIOBTN_PERUSER
All users profile | Radio Button | CTRL_RADIOBTN_ALLUSERS | IDS_CTRL_RADIOBTN_ALLUSERS
Timer | Timer | N/A | N/A


Overview

Static Text Screen

Overview Properties Advanced

The Static Text screen is one type of screen available in Setup Factory. It was designed to allow you to present up to a few paragraphs of static text information to the user.

This screen type is used for various pre-made screens available in Setup Factory. These include the Welcome screen, Finished screen and Ready to Install screen.

The Static Text screen is available in the Screen Gallery, which can be accessed by choosing Project > Screens... from the program menu and clicking the Add button from the Before Installing or After Installing tabs, or from the Before Uninstalling or After Uninstalling tabs in the uninstall section.

This screen type contains the following two categories of settings:

  • Properties

  • Advanced


Properties

Static Text Screen

Overview Properties Advanced

The Static Text screen's properties dialog contains the following four tabs of properties you can set:

  • Settings

  • Attributes

  • Style

  • Actions

Settings

Screen Text

Text:

The text you want to appear in the body of the screen.

Show heading:

Show a heading for the screen body text.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.

Attributes

The screen's attributes tab contains generic settings such as its design-time name, window title, banner style and text and various button settings. The details of this tab's contents are explained in the Screen Attributes topic.

Style

The Style tab is used to customize the screen's appearance beyond the global project theme.

Override project theme

Override the global project theme in order to customize the appearance of the current screen. These settings are the same as the Theme Properties dialog, except they only affect the current screen.

Note: Unchecking this option after changes have been made will restore the default theme settings. Any changes made to these settings will be lost.

Tip: If you are editing a screen and you have the Override project theme selected, you can right click on the screen preview and select "Save as Theme..." to save the created theme.

Actions

The Actions tab contains the action editor dialog where you can add actions or scripts to each event supported by the screen.

Note: Some events will already contain action script and should not be modified unless you want to customize the default behavior of the screen.

The Static Text screen contains the following screen events:

  • On Preload

  • On Back

  • On Next

  • On Cancel

  • On Help

  • On Ctrl Message

Tip: You can use the On Ctrl Message event to detect and respond to user interaction. See the Advanced topic for the list of control IDs and string IDs that are available on this screen.

Tip: You can click on one of the event names above for a full description.


Advanced

Static Text Screen

Overview Properties Advanced

The following table contains the necessary information to manage and manipulate this screen at runtime.

Each type of control fires unique notification messages to signal what type of interaction occurred. Details about each notification message can be found in each control type's topic.

The String ID represents the text that appears on the control. You can use this ID with the Screen.GetLocalizedString action to get the appropriate text for the current language on the user's system.

Control Name | Control Type | Control ID | String ID
Window title | part of screen | N/A | IDS_WINDOW_TITLE
Header text | part of screen | N/A | IDS_HEADER_TEXT
Subheader text | part of screen | N/A | IDS_SUBHEADER_TEXT
Help button | Button | CTRL_BUTTON_HELP | IDS_CTRL_BUTTON_HELP
Back button | Button | CTRL_BUTTON_BACK | IDS_CTRL_BUTTON_BACK
Next button | Button | CTRL_BUTTON_NEXT | IDS_CTRL_BUTTON_NEXT
Cancel button | Button | CTRL_BUTTON_CANCEL | IDS_CTRL_BUTTON_CANCEL
Body header | Static Text | CTRL_HEADINGTEXT_BODY | IDS_CTRL_HEADINGTEXT_BODY
Body text | Static Text | CTRL_STATICTEXT_BODY | IDS_CTRL_STATICTEXT_BODY
Timer | Timer | N/A | N/A


Security - Overview

Security

Overview Serial Numbers Expiration

Many developers integrate security both in their software product, as well as their installation in order to minimize its use by unauthorized individuals.

The Security dialog contains two types of security for your install. The Serial Numbers tab allows you to create and manage the serial number list(s) you wish to integrate into your setup. During your install, you can prompt the user for their serial number or password and validate it by comparing it to the entries in your encrypted serial number list. This can all be done automatically using the Verify Serial Number screen.

The second form of security that can be configured can be found on the Expiration tab of the Security dialog. These settings can be used to make an install expire (cease to run) under certain situations. For example, an install can be configured to expire after a certain number of days, or the number of times it has been run. If the install determines that it has expired, the user will be notified using an abort dialog.

The Security dialog tabs can be accessed from the Project program menu.

The Security dialog contains the following two categories:

  • Serial Numbers

  • Expiration


Serial Numbers

Security

Overview Serial Numbers Expiration

The Serial Numbers tab is where you can create, delete and modify lists of serial numbers to include in your installer. These serial number lists can then be assigned to Verify Serial Number screens to control access to individual features or even the whole installation at run time.

Serial Number Lists:

List Name

The name of the serial number list.

Count

The number of serial numbers in the serial number list.

Build Configurations

The build configurations the selected serial number list applies to.

Add

Opens the Serial Numbers List Properties dialog, where you can create a new serial number list.

Remove

Removes the currently selected serial number list from your project.

Edit

Allows you to edit the currently selected serial number list using the Serial Numbers List Properties dialog.


Expiration

Security

Overview Serial Numbers Expiration

The Expiration tab allows you to incorporate some basic expiration features in your install. If the install matches the expiration criteria, the user will be notified with a dialog before aborting the installation process.

Date Expiration

Enable date expiration

Enable the date expiration feature. If the expiration criteria has been met, the user will be notified and the installation will abort.

Use absolute date:

Make the current install expire on the specified date, for example, 06/25/2015. You can click the select button to bring up a calendar where you can select an expiration date. If the system date is greater than or equal to this date, the user will be notified and the installation will abort.

Expire X days after build

Make the current install expire the specified number of days after being generated. The expiration count down will start after you click the Build button in Setup Factory.

Expire X days after first run

Make the current install expire the specified number of days after being run the first time on that particular system.

Note: When the install is run for the first time on a system, the date is stored in the registry. Subsequent installs will compare the current date to the installed date. Because the registry is system specific, if the install is run on a second system, it will function as if it has not previously been installed.

Abort if Registry not writable

Abort the install if the user is not able to write to the registry to create/modify the install expiration information. If the permissions are not sufficient, the user will be notified that the install will abort.

Display number of days left

Display how many days the user has left to run the installation.

Usage Count Expiration

Enable usage count expiration

Enable the usage count expiration feature. If the expiration criteria has been met, the user will be notified and the installation will abort.

Limit to X installs per system

Limit the number of times the user can run the installation on their system. The install count will be incremented if any files are installed on their system.

Limit to X installs per user

Limit the number times the current user can launch the installation executable. The install count will be incremented if any files are installed by the current user.

Note: Similar to the date expiration feature, the install count refers to a count kept in the system's registry. This feature is system specific, and does not keep track of the file usage in the file itself.

Abort if Registry not writable

Abort the install if the user is not able to write to the registry to create/modify the install count. If the permissions are not sufficient, the user will be notified that the install will abort.

Display number of uses left

Display the number of times the install can be run again.

Settings

Unique product identifier:

A unique string used to identify the install. The end user will not see this information at any time. This string can be entered directly, or you can click the Create button to automatically generate a random product ID.

Show contact information

Show contact information on the abort dialog. The following information can be shown:

Contact name:

A contact name for the product. By default this field contains the session variable %CompanyName%.

Contact URL:

A contact URL for the product. By default this field contains the session variable %CompanyURL%.

Contact email:

A contact email address for the product.

Contact phone:

A contact telephone number for the product.


Tools - Overview

Tools

Overview

The following tools are available in Setup Factory:

  • Generate Project Report

  • Scan Dependencies

  • Scan Visual Basic Project

  • Calculate File CRC


Generate Project Report

Overview

Setup Factory's project report is a textual report that is generated in HTML format, listing all of the settings in the current project file.

Save report file to:

The full path and filename of the report file that you want to create. You can click the Browse button to select an existing file.

Include in report:

The categories you want to include in the generated project report. You can check the boxes of the categories you want to include.

Display report after generation

Automatically display the generated report in your default HTML viewer.


Scan Dependencies

Overview

This tool can be used to scan a Portable Executable (PE) file for dependencies and add them to your Setup Factory project. A Portable executable is an executable file that is portable across all 32-bit Microsoft operating systems. Each Portable Executable (or "PE") file will run on all versions of Windows.

Dependency files are external support files that an executable requires for proper operation. In other words, they are external files that a program file "depends on" in order to function properly. Dependency files may include INI files, DLLs, ActiveX controls, OCX components, or any other support file type. Although it's generally preferable to install dependency files in the same directory as the program that needs them, they are often installed in other locations, such as the Windows system directories.

File to scan:

The Portable Executable file that you want to scan. You can click the Browse button to select a file.

Exclude files in negative file list

Exclude dependency files that are in Setup Factory's negative dependency file list.

The negative file list is located in a file called negativelist.ini, which is located in the Data subdirectory of the Setup Factory application directory on your hard drive. You can edit the list with a text editor if you need to add or remove negative files to suit your needs. In general, you should leave the Exclude files in negative list option enabled in order to avoid shipping core system files with your installer. Replacing core system files could damage your user's operating system.

The following dependency files will be added to the project when you select OK:

A list all of the files that were determined to be dependencies of the file in the File to scan field. You can remove files from this list using the Remove button.

Remove

Remove the selected file from the dependency list.

Scan Now

Begin scanning the specified file for its dependencies.


Scan Visual Basic Project

Overview

This tool can be used to scan a Visual Basic project file for dependencies and add them to your project.

Dependency files are external support files that an executable requires for proper operation. In other words, they are external files that a program file "depends on" in order to function properly. Dependency files may include INI files, DLLs, ActiveX controls, OCX components, or any other support file type. Although it's generally preferable to install dependency files in the same directory as the program that needs them, they are often installed in other locations, such as the Windows system directories.

Note: Scanning your VB project file will not add the project's executable. You will have to add that file manually. The VB Project scanner will only add dependency (DLL and OCX) files.

Note: The appropriate core runtime files for Visual Basic will also be added to the project in the form of a Dependency Module. All dependency modules that have been included automatically can be found by going to Resources > Dependencies...

Visual Basic Version

The version of Visual Basic that was used to create the project file you're scanning. Choose from:

Visual Basic 5.0

The project file was created using version 5.0 of Visual Basic.

Visual Basic 6.0

The project file was created using version 6.0 of Visual Basic.

Project Information

Project file to scan:

The full path and filename of the project file to scan. Visual Basic projects have the .vbp file extension. You can click the Browse button to select a project file from your system.


Calculate File CRC

Overview

File name:

The full path to the file you want to calculate the CRC value of. You can click the Browse button to select a file from your system.

Tip: If a file in your file list is currently highlighted, its CRC value will automatically be calculated for you without having to browse for it.

CRC value:

The CRC value of the specified file.

Copy

Copies the value in the CRC value field to the Windows clipboard so you can paste it somewhere within your install. You can paste the value by selecting Paste from the right-click context menu, or using Ctrl+V on your keyboard.


Uninstall Screens - Overview

Uninstall Screens

Overview Before Uninstalling While Uninstalling After Uninstalling

The Uninstall Screens dialog is where you can add, remove, arrange, preview, export and configure all of the screens you want to show during the uninstall process.

There are three tabs on the Uninstall Screens dialog: the Before Uninstalling tab, the While Uninstalling tab, and the After Uninstalling tab. These three tabs represent the three different times during the uninstall process when screens can be shown.

At run time, the screens are displayed in the same order as they're listed on these tabs.

Screen text can also be translated for each language that is supported by your setup. A language selector can be found on the Settings tab of each screen's properties dialog so you can quickly translate this text.

To access the Uninstall Screens dialog, choose Uninstall > Screens... from the program menu.

There are three locations you can add screens to your uninstall:

  • Before Uninstalling

  • While Uninstalling

  • After Uninstalling


Before Uninstalling

Uninstall Screens

Overview Before Uninstalling While Uninstalling After Uninstalling

The screens listed on the Before Uninstalling tab will be shown before any files are removed from the user's system and before the While Uninstalling screen is shown. Each screen will be shown in sequential order, the first screen being shown right after the uninstall is launched.

Screens:

The screens that will appear after the uninstall starts, up until the point in which the files are going to be removed. The order that these screens appear in the list is the order that they will be shown at runtime.

Screen ID

The identifiers of all of the currently added screens to be displayed before the files are removed.

Screen Type

The screen types of all of the currently added screens.

Preview:

An image preview of the selected screen.

Note: Some contents of the screen preview may not be accurate if it requires information that must be gathered during the uninstall process.

Add

Open the Screen Gallery dialog where you can add a new screen to the screen list.

Remove

Remove the selected screen from the screen list.

Edit

Open the selected screen's properties dialog where you can configure its settings.

Up ( )

Move the selected screen up one position in the Before Uninstalling screen list.

Down ( )

Move the selected screen down one position in the Before Uninstalling screen list.

Advanced

Add to Gallery...

Opens the Add to Gallery dialog where you can add a custom screen to the global screen gallery.

Export Language

Expands to a menu containing all languages in the project available for export. Clicking on a language will open a Save As dialog so you can choose the path that the selected language will be exported to. A dialog message will notify you of success or failure.

Import Language...

Open a file browse dialog so you can select a screen's language XML file that you want to import into the currently selected screen. A dialog message will notify you of success or failure.


While Uninstalling

Uninstall Screens

Overview Before Uninstalling While Uninstalling After Uninstalling

The While Uninstalling tab is used to configure the type of progress screen you want to show while your application's files are being removed.

Show progress screen during install

Whether to show a progress screen during the uninstall process.

Progress Screen

Type:

The type of progress screen currently configured to display during the removal of the application files.

Change

Open the Screen Gallery dialog where you can select a different progress screen.

Edit

Open the selected progress screen's properties dialog so you can configure its settings.

Advanced

Add to Gallery...

Opens the Add to Gallery dialog where you can add a custom progress screen to the global screen gallery.

Export Language

Expands to a menu containing all languages in the project available for export. Clicking on a language will open a Save As dialog so you can choose the path that the selected language will be exported to. A dialog message will notify you of success or failure.

Import Language...

Open a file browse dialog so you can select a screen's language XML file that you want to import into the currently selected screen. A dialog message will notify you of success or failure.

Preview:

An image preview of the currently selected progress screen.

Note: Since this screen displays dynamic content during the uninstall, some content will not appear during a preview of the screen.


After Uninstalling

Uninstall Screens

Overview Before Uninstalling While Uninstalling After Uninstalling

The screens listed on the After Uninstalling tab will follow the progress screen configured on the While Uninstalling tab. At this point, all files have been removed from the user's system. Each screen will be shown in sequential order from top to bottom.

Screens:

The screens that will appear after the files have been uninstalled. The order that these screens appear in the list is the order that they will be shown at runtime.

Screen ID

The identifiers of all of the currently added screens to be displayed after the files have been uninstalled.

Screen Type

The screen types of all of the currently added screens.

Preview:

An image preview of the selected screen.

Note: Some contents of the screen preview may not be accurate if it requires information that must be gathered during the uninstall process.

Add

Open the Screen Gallery dialog where you can add a new screen to the screen list.

Remove

Remove the selected screen from the screen list.

Edit

Open the selected screen's properties dialog where you can configure its settings.

Up ( )

Move the selected screen up one position in the After Uninstalling screen list.

Down ( )

Move the selected screen down one position in the After Uninstalling screen list.

Advanced

Add to Gallery...

Opens the Add to Gallery dialog where you can add a custom screen to the global screen gallery.

Export Language

Expands to a menu containing all languages in the project available for export. Clicking on a language will open a Save As dialog so you can choose the path that the selected language will be exported to. A dialog message will notify you of success or failure.

Import Language...

Open a file browse dialog so you can select a screen's language XML file that you want to import into the currently selected screen. A dialog message will notify you of success or failure.


Uninstall Settings- Overview

Uninstall Settings

Overview Settings Background Control Panel Shortcut Logs

The uninstall settings dialog contains various settings that are used to configure the uninstall program for your installation. Some of these settings include: The option of including an uninstall program; information that will be displayed in the Control Panel; shortcuts that will be created on the user's system; and debug log file creation during the uninstall process.

Each tab on the Uninstall Settings dialog can be accessed from the Uninstall program menu.

The Uninstall Settings dialog contains the following five categories:

  • Settings

  • Background

  • Control Panel

  • Shortcut

  • Logs

Tip: To require that the user has administrative privileges to run the uninstallation, configure the installation to require administrative privileges. This can be done from the Requirements dialog.


Settings

Uninstall Settings

Overview Settings Background Control Panel Shortcut Logs

Create uninstall

Automatically create an uninstall program for your application.

File Names and Locations

Uninstall files folder:

The folder that the uninstall's resource files will be stored in on the user's system. Normally this is %AppFolder%\Uninstall.

Tip: During the uninstall, the global variable _TempLaunchFolder and the session variable %TempLaunchFolder% are both set to the uninstall files folder.

Configuration filename:

The unique filename of the uninstall's configuration file. This file is one of the uninstall's resources that will be created in the Uninstall files folder.

Executable path and filename:

The path and filename of the uninstall executable that will be created on the user's system. Normally this file is created in %AppFolder%\uninstall.exe.

If Uninstall Already Exists

Overwrite data file

If the uninstall data file already exists in the Uninstall files folder, overwrite the existing file. If this option is unchecked, the existing data file will be used for the uninstall.

Overwrite control panel entry

If there is an existing control panel entry for the install, overwrite it with the new control panel settings. If unchecked, the existing control panel entry will be used.

Overwrite uninstall shortcut

If an uninstall shortcut already exists, overwrite it with the new uninstall shortcut. If unchecked, the existing shortcut will be used for the uninstall.

Options

Allow silent uninstall

Enable the uninstall to be run in "silent mode" using the /S command line option. This means that there will be no user interaction required during the uninstallation process. If you are performing silent uninstallations, it is highly recommended that you use a log file during the uninstall process so that you can debug if problems occur. You can enable the uninstall's log file on the Logs tab of the Uninstall Settings dialog.

Note: Uninstall screen actions will only be executed if the screens are displayed, therefore when run in silent mode, no screen actions will be executed.

Start in silent mode

Start the uninstall in "silent mode" by default. If unchecked, you can run your uninstall in silent mode using the command line option /S. Selecting this option sets the global variable _SilentInstall to true.

Always on top

Make the uninstall window always appear on top of all other windows on the desktop. The window will remain on top even if the user switches to another application.


Background - Uninstall

Uninstall Settings

Overview Settings Background Control Panel Shortcut Logs

The background window is a large window that your uninstallation window will sit on at runtime. The background window may be a solid color, gradient color, or even an image. Below are the settings used to configure how this background window should look throughout your uninstall.

Show background window

Show a background window behind the main uninstallation window.

Style

Standard

Show a title bar and border for the background window.

Bordered

Show a border around the background window with no title bar.

Kiosk

Make the background window cover the entire screen without a title bar or border.

Appearance

Solid color:

Make the background window a solid color. Click the select button ( [image] ) to bring up a color chooser.

Gradient:

Create a gradient color background by blending two colors together. The first color represents the color that will appear at the top of the background window and the second color represents the bottom color that it will be blended into. You can click the select button ( [image] ) to bring up a color chooser for each color.

Image:

Insert an image into the background window. Click the Browse button to select the image file you want to use. The following image formats are supported:

*.bmp; *.gif; *.jpg; *.pcx; *.png; *.tga; *.tif

Note: The specified image file will be stretched to fit the dimensions of the background window.

Text

Heading:

The text that will appear along the top of the background window. You can click the Font button to choose the font you want to use for the text, and the select ( [image] ) button to choose the text color.

Left

Align the heading text to the left hand side of the background window.

Center

Center the heading text on the background window.

Right

Align the heading text to the right hand side of the background window.

3D

Give the heading text a three-dimensional effect. You can click the select ( [image] ) button to choose the text shadow color you want to use.

Subheading:

The text that will appear below the heading text on the background window. You can click the Font button to choose the font you want to use for the text and the select ( [image] ) button to choose the text color.

Left

Align the subheading text to the left hand side of the background window.

Center

Center the subheading text on the background window.

Right

Align the subheading text to the right hand side of the background window.

3D

Give the subheading text a three-dimensional effect. You can click the select ( [image] ) button to choose the text shadow color you want to use.

Footer:

The text that will appear along the bottom of the background window. You can click the Font button to choose the font you want to use for the text and the select ( [image] ) button to choose the text color.

Left

Align the footer text to the left hand side of the background window.

Center

Center the footer text on the background window.

Right

Align the footer text to the right hand side of the background window.

3D

Give the footer text a three-dimensional effect. You can click the select ( [image] ) button to choose the text shadow color you want to use.


Control Panel

Uninstall Settings

Overview Settings Background Control Panel Shortcut Logs

List uninstall in "Add or Remove Programs" (Control Panel)

List your application in the "Add/Remove Programs" section of the user's Control Panel.

Entry Settings

Description:

The description text you want to display in the "Add/Remove Programs" list.

Unique registry key:

The unique registry key where you want to store your uninstall settings. This key is used to uniquely identify the uninstall information for your application.

Note: The location of the unique registry key is based on the chosen Requested User Privilege Level of the setup. By default it will be created at the following location: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall. However, if "As invoker" is chosen, it will be created in HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall.

Icon mode:

The icon mode you want to use for the Control Panel entry. Choose from:

Default

Display the default uninstall icon in the "Add/Remove Programs" list.

Custom

Display a custom uninstall icon in the "Add/Remove Programs" list.

Filename:

The path to the icon file that will be used to in Add/Remove Programs. The file must be a valid Windows icon (.ico) file. You can click the Browse button to open the Insert File Reference where you can select an existing standard icon (.ico) file from your project, or add one. After the file has been selected, this field will contain the location to reference the icon file after it has been installed on the user's system.

Icon Index:

The index of the icon you want to use from the file specified in Filename. If there is only one icon in the file, or if you want to use the first icon found in the file, enter "0" here.

Support Info

The following is a list of additional information that can be displayed in the "Add/Remove Programs" list for your application's uninstall. Many of these values contain the default session variables defined on the Session Variables tab of the Project Settings dialog:

Publisher

The publisher of your application. By default this contains the company name for the project, %CompanyName%.

Publisher URL

The publisher's URL. By default this contains the project's URL %CompanyURL%.

Help Contact

The title of the support department for your application. By default this contains %CompanyName% Support Department.

Help URL

The URL to display for product support information. By default this contains %CompanyURL%.

Product Version

The product version of your application. By default this contains %ProductVer%.

Registered Owner

The registered owner of the application. This option does not contain a default session variable.

Registered Company

The company the application is registered to. This option does not contain a default session variable.

Update Info URL

A URL containing product update information for your application. This option does not contain a default session variable.

Readme File

A path to a Readme file for your application. This option does not contain a default session variable.

Comments

Additional comments you want to display in the "Add/Remove Programs" section of your application. This option does not contain any default information.

InstallLocation

The full path to your application's primary folder. By default this contains %AppFolder%.

VersionMajor

The major version of your application. This is the first field in the format major.minor.build.

VersionMinor

The minor version of your application. This is the second field in the format major.minor.build.


Shortcut

Uninstall Settings

Overview Settings Background Control Panel Shortcut Logs

Create uninstall shortcut in Start menu > AppFolder

Create a shortcut in the application folder (%AppShortcutFolderName%) of the user's Start Menu to launch the uninstall program.

Properties

Description:

The description text that you want to display for the uninstall's shortcut.

Comment:

The comment that you want to display for the uninstall's shortcut.

Icon

Mode:

The icon mode you want to use for the uninstall shortcut. Choose from:

Default

Use the default uninstall icon for the uninstall's shortcut.

Custom

Use a custom icon for the uninstall's shortcut:

Icon path:

The path to the icon file that will be used to represent this shortcut on the user's system. The file must be a valid Windows icon (.ico) file. You can click the Browse button to open the Insert File Reference where you can select an existing standard icon (.ico) file from your project, or add one. After the file has been selected, this field will contain the location to reference the icon file after it has been installed on the user's system.

Icon index:

The index of the icon you want to use from the file specified in Icon path. If there is only one icon in the file, or if you want to use the first icon found in the file, enter "0" here.


Logs

Uninstall Settings

Overview Settings Background Control Panel Shortcut Logs

Create log file

Generate a log file during the uninstall of your application. The uninstall log file is in ASCII text format and provides information about what happened during the uninstall process, such as which files were uninstalled, which programs were executed, what Registry changes were made, etc. This information can be extremely useful if you ever need to debug an uninstall where errors occurred, or where contents were not removed as expected.

Log File

Filename:

The location and filename of the log file to generate during the uninstall. You can specify an absolute location such as C:\Temp or you can use session variables to form dynamic paths such as %TempFolder%\UninstallLog.txt.

Note: Since the uninstall cannot remove a directory unless it is completely empty, you should not create this file in your application's directory. We recommend using a standard external location such as %TempFolder%, or %WindowsFolder% for this file's creation.

Write mode:

How the log file will be updated if there is currently a log file in the target location. Choose from:

Append

Append any new log file entries to the end of the existing file.

Overwrite

Overwrite the existing log file when generating the current one.

Include action details:

The action details that will be included in the log file. Choose from:

None

Don't log any errors in scripts in the log file.

Errors

Log errors in scripts with the event the error occurred in, the line it occurred on and the error message or code.

Extended Errors

Same as Errors but the actual line of code executed will be reported as well (if available).


Variables - Overview

Variables

Overview Global Variables Session Variables Design-time Constants

There are three types of built-in variables that were designed for different purposes in Setup Factory. The first type are called Global variables that are expanded once at the beginning of the setup. These variables were designed to be used in action script for common values that might differ between systems.

The second type of built-in variable are called Session variables. This type was designed to be used for values that may change during the installation process. They are most commonly used to display dynamic content on screens and use as file destinations.

The third type of built-in variable are called Design-time constants. While the previous two types are expanded at run time, design-time constants are expanded during the build process. Normally this type is used for settings such as the product version, or dates of the build etc.

A list of the available built-in variables can be found in each of the following categories:

  • Global variables

  • Session variables

  • Design-time Constants

Tip: Often global variables are used as part of a full path where you need to join two strings together. For example, you may need a path consisting of the user's Program Files folder and a program folder such as "ApplicationX." To do this, you would use the string concatenation operator which consists of two dots (..). The script looks like this:

_ProgramFilesFolder .. "\\ApplicationX"

You can also use the String.Concat action to concatenate two strings.

Note: There are also a series of actions available that can be used to gather information about the user's system that may not be part of the built-in variables list. For example, additional common folder paths can be read using the Shell.GetFolder action. There is also a System category of actions for other system information.

For more information on variables, see Variables in the Scripting Guide.


Global Variables

Variables

Overview Global Variables Session Variables Design-time Constants

Global variables are variables whose values are automatically set when your installation starts. They are used in action script to represent common values that might differ between systems. These variables are all global which means you can use them anywhere in your project.

Tip: The built-in global variables are listed along with all of the actions and constants when you press Ctrl+Space in the action editor. Since all of the built-in variables start with an underscore, if you type _ and then press Ctrl+Space, you'll be taken right to the first built-in global variable in the list.

The following global variables are available in Setup Factory:

_BackupFolder

The folder that files with the Create backup option enabled will be backed up to at runtime. If not defined, backup files are created in the same folder as the target file. By default, this variable is undefined.

Tip: The best place to define this variable is On Pre Install so that all installation folders are defined:
_BackupFolder = SessionVar.Expand("%AppFolder%\\Backup");

_CommandLineArgs

A numerically indexed table that contains the command line arguments passed into the installation executable.

_DesktopFolder

The path to the user's Desktop folder.

_DesktopFolderCommon

The path to the All Users profile Desktop folder.

_DisableCloseButton

Whether or not the close button (X) will be disabled on screens. If this boolean variable is set to true the close button will be disabled. If the value is false (by default), it will be enabled. This variable can only be set from a project event such as On Startup. It will then affect any screens displayed after that point.

_DoingUninstall

Whether or not the uninstall is currently being performed. If true is returned, Setup Factory is in the uninstall process. If false is returned, Setup Factory is in the install process. This variable may be useful for Global Functions that you want to use for both the install and uninstall but rely on which stage the setup is in.

_InstallStages

A table of Boolean values that control whether certain install stages are executed at runtime. Initially these values are set to true. If you want to skip a future install stage, you can set its table entry to false. The install stage table contains the following indexes that can be set:

"ExpirationCheck"
"SystemRequirementsCheck"
"IncludeGlobalScripts"
"IncludeGlobalFunctions"
"RunOnStartupActions"
"ShowBeforeInstallingScreens"
"RunOnPreInstallActions"
"ShowWhileInstallingScreen"
"InstallArchiveFiles"
"InstallExternalFiles"
"CreateFileShortcuts"
"CreateUninstall"
"RunOnPostInstallActions"
"ShowAfterInstallingScreens"
"RunOnShutdownActions"
"CheckDependencies"

Note: These values simply control whether or not the "stage" will be executed. For example, if you did not have an uninstall program set to be created, you cannot enable its actual creation by setting "CreateUninstall". This feature is mainly used for skipping stages.

_IR_ProductID

This variable contains the string "SUF9" when used in Setup Factory. This allows you to identify the product being run from script. This could be useful when making generic scripts that are used in several products, but that have different things to do based on the product being run from.

_NeedsReboot

Whether or not the system needs to be restarted at the end of the install or uninstall process in order to install/uninstall files that were in use. This variable is initially set to false when the install or uninstall starts and is set to true if the system needs to be restarted.

Note: If the install needs to be rebooted, a dialog prompt will be shown automatically asking whether or not a reboot should proceed. The dialog and reboot action that are automatically added to each project on the On Shutdown event are defined in the function g_HandleSystemReboot() which can be found in the global script file _SUF70_Global_Functions.lua.

_ProgramFilesFolder

The user's Program Files folder (typically, this is something like "C:\Program Files").

_ProgramFilesFolder64

The user's Program Files folder on 64-bit operating systems. On 32-bit systems, the value is equal to _ProgramFilesFolder.

_SilentInstall

Whether or not the install should be run in "silent mode". Initially this value is set to the boolean value false, but if set to true the install will be run silently.

In silent mode, no user interface is presented to the user at all; any screens or dialog messages will not be shown.

Note that although you can change the value of _SilentInstall at any time, you should only switch to or from silent mode on one of the four "main" action tabs:

On Startup

On Pre Install / On Pre Uninstall

On Post Install / On Post Uninstall

On Shutdown

Changing the value of _SilentInstall at any other point will have no effect on any screens or progress displays until the next "main" action tab is reached.

Tip: This variable can also be set using the command line option /S or by selecting the Start in silent mode option at design time.

_SourceDrive

The drive that the installation executable was run from (e.g. "C:" or "D:").

_SourceFilename

The full path and filename of the installation executable (e.g. "C:\Downloads\setup.exe").

_SourceFolder

The full path to the folder that the installation executable was run from (e.g. "C:\Downloads" or "D:\").

_SuppressUninstallDataDuplicateCheck

Whether or not to check the uninstall configuration file for existing entries when installing archive and external files. By default this variable is undefined, but when set to the boolean value true, duplicate file checking will be skipped when writing out file data to the uninstall configuration file. If the variable is undefined or is false, duplicate file checking will be performed. This variable must be defined before the installing files stage.

Note: This variable is generally only used in very large installs where large amounts of files are being installed. In these cases, it will generally increase the speed of installing the files. However, this also means that there may be duplicate entries in the uninstall configuration file if the user installed over top of an existing setup. In this case, the uninstall will still function correctly, but may need to be addressed if you are manually querying the uninstall configuration file.

_SystemFolder

The path to the user’s Windows System folder (e.g. "C:\Windows\System32").

_tblErrorMessages

A table indexed by error codes containing all of the possible error messages. For example, accessing the table index _tblErrorMessages[1000] will access the error code string "The specified file could not be found." The Application.GetLastError action is used to retrieve the last performed action's error code.

_TempFolder

The path to the user's Temp folder.

_TempLaunchFolder

The path to the temporary directory where Setup Factory extracts the files it will need for the installation. (For example, this is the directory where Primer files are extracted to.) During the uninstall, this variable contains the path to the uninstall files folder. This is the folder that the uninstall configuration file is located.

Usually this directory will be the user's temporary directory, unless the user overrides the temporary directory with the /T command line option.

_UninstallStages

A table of Boolean values that control whether certain uninstall stages are executed at runtime. Initially these values are set to true. If you want to skip a future uninstall stage, you can set its table entry to false. The uninstall stage table contains the following indexes that can be set:

"IncludeGlobalScripts"
"IncludeGlobalFunctions"
"RunExtraScripts"
"RunOnStartupActions"
"ShowBeforeUninstallingScreens"
"RunOnPreUninstallActions"
"ShowWhileUninstallingScreen"
"UninstallFiles"
"UninstallFileShortcuts"
"RunOnPostUninstallActions"
"ShowAfterUninstallingScreens"
"RunOnShutdownActions"
"RemoveUninstallFiles"

Note: This table can only be modified during the uninstall. Setting them during the install has no effect.

_UsePerUserFolders

Whether or not shortcuts are created in the per user, or all user profile on XP/Vista or later systems. If this variable contains true, the per user profile will be used and if it contains false, the all user profile will be used. Initially this value is taken from the Default User Profile for Shortcuts setting in the advanced project settings. This value can also be set by the end user at run time on the Select Shortcut Folder screen.

_UseSystemCharacterSet

If set to true, Setup Factory will use the system's default character set (script) for text elements on screens when using custom fonts ("Use Custom Fonts" set to True), overriding it's font script setting. This makes the text font behave like Setup Factory's default settings when working with multiple languages. If you wish to use this variable, it's recommended that you set it very early in the setup. This variable defaults to false.

_WindowsFolder

The path to the user's Windows folder (e.g. "C:\Windows").


Variables - Session Variables

Variables

Overview Global Variables Session Variables Design-time Constants

Session variables are special types of variables that are expanded at runtime when they are used. When they are used on screens, their values are automatically expanded for you, however if a session variable is used in an action script, it must be manually expanded using the SessionVar.Expand action.

While there are predefined session variables available to use, you can also create custom session variables at design time and run time. At design time, they can be defined on the Session Variables tab of the Project Settings dialog. At run time, you can create and manipulate session variables using the available SessionVar actions.

Note: If a session variable used on a screen needs to be set to a different value, it must be set prior to the screen's displaying, and all of its events. Another option is to set the text of the screen control using the appropriate Dlg***.SetProperties action. Any changes made to a session variable on a screen after the screen has been created (just before the On Preload event) will have no effect.

The following pre-defined session variables are available in Setup Factory:

%AppFolder%

Your application's main directory, where all of your files and folders will be installed. For example, by default Setup Factory's main directory is C:\Program Files\Setup Factory 9.

%AppFolder% is initially set to the default value that you give it on the Session Variables tab of the Project Settings dialog. However, in most installations, the value of %AppFolder% will ultimately be set by the user on the Select Install Folder screen, overriding the default value.

%ApplicationDataFolder%

The path to the Application Data folder on the user's system. This folder serves as a common repository for application-specific data. Typically, this path is something like "C:\Documents and Settings\YourName\Application Data." On Windows Vista or later, it would return something like "C:\Users\YourName\AppData\Roaming."

%ApplicationDataFolderCommon%

The path to the All Users profile Application Data folder on the user's system. This folder servers as a common repository for application-specific data. Typically this is something like "C:\Documents and Settings\All Users\Application Data." On Windows Vista or later, this returns "C:\ProgramData."

%AppShortcutFolderName%

The name of the shortcut folder on the Start menu where your application's shortcuts will be stored.

%AppShortcutFolderName% is initially set to the default value that you give it on the Session Variables tab of the Project Settings dialog. However, in many installations, the value of %AppShortcutFolderName% will ultimately be set by the user on the Select Shortcut Folder screen, overriding the default value %ProductName%.

%AppDrive%

The drive letter of %AppFolder%. You should not set this variable explicitly. It is reset every time that %AppFolder% is re-assigned. For example, if %AppFolder% is C:\Program Files\My Program, %AppDrive% will be C:.

%CommonDocumentsFolder%

The path to the documents folder common to all users. Usually this is something like "C:\Documents and Settings\All Users\Documents."

%CommonFilesFolder%

The user's Common Files folder. Typically, this is something like: C:\Program Files\Common Files.

%CommonFilesFolder64%

The user's Common Files folder on 64-bit operating systems. On 32-bit systems, the value is equal to %CommonFilesFolder%.

%CompanyName%

Your company’s name. The value of this variable is set on the Session Variables tab of the Project Settings dialog.

%CompanyURL%

Your company’s URL. The value of this variable is set on the Session Variables tab of the Project Settings dialog.

%Copyright%

The copyright message for your product. The value of this variable is set on the Session Variables tab of the Project Settings dialog.

%DAOPath%

The path to the user's DAO (Data Access Objects) directory.

%DesktopFolder%

The path to the user's Desktop folder.

%DesktopFolderCommon%

The path to the All Users profile Desktop folder.

%FontsFolder%

The path to the user’s font directory (e.g. "C:\Windows\Fonts").

%LaunchUserApplicationDataFolder%

The path to the Application Data folder of the user who launched the setup when Collect launch user information is selected. This folder serves as a common repository for application-specific data. Typically, this path is something like "C:\Documents and Settings\YourName\Application Data." On Windows Vista or later, it would return something like "C:\Users\YourName\AppData\Roaming."

%LaunchUserDesktopFolder%

The path to the Desktop folder of the user who launched the setup when Collect launch user information is selected.

%LaunchUserDomain%

The domain name associated with the launch user SID when Collect launch user information is selected.

%LaunchUserMyDocumentsFolder%

The personal (My Documents) folder of the user who launched the setup when Collect launch user information is selected. Usually this is something like "C:\Documents and Settings\YourName\My Documents" on Windows XP, and "C:\Users\YourName\Documents" on Windows Vista or later.

%LaunchUserMyMusicFolder%

The path to the My Music folder of the user who launched the setup when Collect launch user information is selected. For example "C:\Documents and Settings\User\My Documents\My Music."

%LaunchUserMyPicturesFolder%

The path to the My Pictures folder of the user who launched the setup when Collect launch user information is selected. For example "C:\Documents and Settings\username\My Documents\My Pictures."

%LaunchUserMyVideosFolder%

The path to the My Videos folder of the user who launched the setup when Collect launch user information is selected. For example "C:\Documents and Settings\username\My Documents\My Videos."

%LaunchUserName%

The account name associated with the launcher user SID when Collect launch user information is selected.

%LaunchUserStartFolder%

The path to the Start menu folder of the user who launched the setup when Collect launch user information is selected.

%LaunchUserStartProgramsFolder%

The path to the Programs folder in the user's Start menu of the user who launched the setup when Collect launch user information is selected.

%LaunchUserStartupFolder%

The path to the Startup folder of the user who launched the setup when Collect launch user information is selected.

%MyDocumentsFolder%

The user's personal (My Documents) folder on their system. Usually this is something like "C:\Documents and Settings\YourName\My Documents" on Windows XP, and "C:\Users\YourName\Documents" on Windows Vista or later.

%MyMusicFolder%

The path to the user's My Music folder. For example "C:\Documents and Settings\User\My Documents\My Music."

%MyMusicFolderCommon%

The path to the All Users profile My Music folder, for example "C:\Documents and Settings\All Users\Documents\My Music."

%MyPicturesFolder%

The path to the user's My Pictures folder. For example "C:\Documents and Settings\username\My Documents\My Pictures."

%MyPicturesFolderCommon%

The path to the All User profile My Pictures folder, for example "C:\Documents and Settings\All Users\Documents\My Pictures."

%MyVideosFolder%

The path to the user's My Videos folder. For example "C:\Documents and Settings\username\My Documents\My Videos."

%MyVideosFolderCommon%

The path to the All User profile My Videos folder. For example "C:\Documents and Settings\All Users\Documents\My Videos."

%ProductName%

The name of the product that you are installing. The value of this variable is set on the Session Variables tab of the Project Settings dialog.

%ProductVer%

The version number of the product that you are installing. The value of this variable is set on the Session Variables tab of the Project Settings dialog.

%ProgramFilesFolder%

The user's Program Files folder (typically, this is something like "C:\Program Files").

%ProgramFilesFolder64%

The user's Program Files folder on 64-bit operating systems. On 32-bit systems, the value is equal to %ProgramFilesFolder%.

%RegOwner%

The name of the registered user of the system.

%RegOrganization%

The organization of the registered user of the system.

%SourceDrive%

The drive that the installation executable was run from (e.g. "C:" or "D:").

%SourceFolder%

The full path to the folder that the installation executable was run from (e.g. "C:\Downloads" or "D:\").

%SourceFilename%

The full path, including the filename, for the current setup executable.

For example, if the user was running "setup.exe" from "C:\Downloads", %SourceFilename% would be expanded to "C:\Downloads\Setup.exe".

%StartFolder%

The path to the user's Start menu folder.

%StartFolderCommon%

The path to the All Users profile Start menu folder.

%StartProgramsFolder%

The path to the Programs folder in the user's Start menu.

%StartProgramsFolderCommon%

The path to the All Users profile Programs folder in the user's Start menu.

%StartupFolder%

The path to the user's Startup folder.

%StartupFolderCommon%

The path to the All Users profile Startup folder.

%SystemFolder%

The path to the user’s Windows System folder (e.g. "C:\Windows\system32").

%SystemDrive%

The drive that the user's Windows System directory is located on (usually "C:").

%TempFolder%

The path to the user's Temp folder.

%TempLaunchFolder%

The path to the temporary directory where Setup Factory extracts the files it will need for the installation. (For example, this is the directory where Primer files are extracted to.) During the uninstall, this variable contains the path to the uninstall files folder. This is the folder that the uninstall configuration file is located.

Usually this directory will be the user's temporary directory, unless the user overrides the temporary directory with the /T command line option.

%WindowsFolder%

The path to the user’s Windows folder (e.g. "C:\Windows").

%WindowTitle%

The text that will appear on the windows task bar while the installation is running. The value of this variable is set on the Session Variables tab of the Project Settings dialog.


Design-time Constants

Variables

Overview Global Variables Session Variables Design-time Constants

Design-time constants are similar to session variables, but instead of being converted to values at run time, design-time constants get converted at build time. We call them design-time constants because the names you give them only exist at design time. At build time, the name of each design-time constant is replaced by the value that was assigned to it.

Tip: You can also define custom design-time constants on the Constants tab found by choosing Publish > Settings from the program menu and selecting the Constants tab.

The following design-time constants are available in Setup Factory:

#ASC????#

This is a special set of design-time constants. When a constant's name starts with "#ASC", Setup Factory interprets the value assigned to that constant as the ASCII value of a character. Wherever you use that constant, Setup Factory replaces the constant's name with the corresponding character.

For example, if you create a design-time constant named #ASC_QUOTE# and assign the value "34" to it, Setup Factory would replace each occurrence of #ASC_QUOTE# in your project with the character whose ASCII number is 34, i.e., a quotation mark ("). Or, you could create a design-time constant to represent the null character (ASCII value 0) by assigning the value "0" to "#ASCNULL#".

#COMMONFILESDIR#

The Common Files folder on your development system. Typically, this is something like: C:\Program Files\Common Files.

#CURRENTDAY#

A number representing the current day of the month, calculated when the setup executable is built.

#CURRENTHOUR#

A number representing the current hour in 24-hour time (e.g. 4:00 PM is 16), calculated when the setup executable is built.

#CURRENTMINUTE#

The current minute, calculated when the setup executable is built. This number is always expressed with two digits, so 4 minutes into the hour will be "04".

#CURRENTMONTH#

A number representing the current month, calculated when the setup executable is built. January is represented by "1" and December is represented by "12".

#CURRENTMONTH2#

A two-digit number representing the current month, calculated when the setup executable is built. January is represented by "01" and December is represented by "12".

#CURRENTSECOND#

The current second, calculated when the setup executable is built. This number is always expressed with two digits, so 4 seconds into the minute will be "04".

#CURRENTYEAR#

The four-digit number representing the current year, calculated when the setup executable is built.

#DATE#

The current date on your development system when the setup executable is built. It's in the format MM/DD/YY. So, if you built the installer on May 23, 2015, #DATE# would be "05/23/15".

#EUROPEANDATE#

The current date on your development system when the setup executable is built, in the European dating format: DD/MM/YY. For example, if you built the installer on May 23, 2015, #EUROPEANDATE# would be "23/05/15".

#ISODATE#

The current date on your development system when the setup executable is built, in the ISO format: YYYY-MM-DD. For example, if you built the installer on May 23, 2015, #ISODATE# would be "2015-05-23".

#JULIANDATE#

The current date on your development system when the setup executable is built, in the form of an integer value representing the number of days since midnight on January 1, 4713 B.C.

You can use #JULIANDATE# along with the System.GetDate action to build setups that expire a certain number of days after they are created. To calculate the number of days that have elapsed since the setup executable was generated, use the formula System.GetDate(DATE_FMT_JULIAN) - #JULIANDATE#.

#PROGRAMFILESDIR#

The path to the Program Files directory on your development system.

#PROJECTFILEDIR#

This is path to the Setup Factory 9 project (.SUF) file that you are currently editing. Your project file must be saved in order for this variable to be properly set. If you have not saved your document, this constant will be set to "C:" by default.

This constant is useful if you want to keep your project (.SUF) file and the files in your setup in the same directory. That way you can set #PROJECTFILEDIR# as the files' source directory and your project will be portable to different development systems where paths and drives may change.

#SUFDIR#

The path to the directory where Setup Factory is installed on your development system. Usually this will be "C:\Program Files\Setup Factory 9".

#SYSDIR#

The path to the system directory on your development system.

#WINDIR#

The path to the Windows directory on your development system.


Miscellaneous

Contents

Please select one of the following subjects:

ASCII Table

Callback Functions

INI Files

Input Mask

Language ID Codes

Quad-state Check Box

System Restore Monitored File Extensions

Tri-state Check Box

Virtual Key Codes

XML Actions Concepts


ASCII Table

Miscellaneous

Contents ASCII Table

ASCII stands for American Standard Code for Information Interchange. Computers can only understand numbers, so an ASCII code is the numerical representation of a character such as 'a' or '@' or an action of some sort. Below is the standard ASCII character set and includes descriptions of the first 32 non-printing characters.

Decimal | Hex | Character |
0 | 0 | NUL | (null)
1 | 1 | SOH | (start of heading)
2 | 2 | STX | (start of text)
3 | 3 | ETX | (end of text)
4 | 4 | EOT | (end of transmission)
5 | 5 | ENQ | (enquiry)
6 | 6 | ACK | (acknowledge)
7 | 7 | BEL | (bell)
8 | 8 | BS | (backspace)
9 | 9 | TAB | (horizontal tab)
10 | A | LF | (NL line feed, new line)
11 | B | VT | (vertical tab)
12 | C | FF | (NP form feed, new page)
13 | D | CR | (carriage return)
14 | E | SO | (shift out)
15 | F | SI | (shift in)
16 | 10 | DLE | (data link escape)
17 | 11 | DC1 | (device control 1)
18 | 12 | DC2 | (device control 2)
19 | 13 | DC3 | (device control 3)
20 | 14 | DC4 | (device control 4)
21 | 15 | NAK | (negative acknowledge)
22 | 16 | SYN | (synchronous idle)
23 | 17 | ETB | (end of trans. block)
24 | 18 | CAN | (cancel)
25 | 19 | EM | (end of medium)
26 | 1A | SUB | (substitute)
27 | 1B | ESC | (escape)
28 | 1C | FS | (file separator)
29 | 1D | GS | (group separator)
30 | 1E | RS | (record separator)
31 | 1F | US | (unit separator)
32 | 20 | Space |
33 | 21 | ! |
34 | 22 | " |
35 | 23 | # |
36 | 24 | $ |
37 | 25 | % |
38 | 26 | & |
39 | 27 | ' |
40 | 28 | ( |
41 | 29 | ) |
42 | 2A | * |
43 | 2B | + |
44 | 2C | , |
45 | 2D | - |
46 | 2E | . |
47 | 2F | / |
48 | 30 | 0 |
49 | 31 | 1 |
50 | 32 | 2 |
51 | 33 | 3 |
52 | 34 | 4 |
53 | 35 | 5 |
54 | 36 | 6 |
55 | 37 | 7 |
56 | 38 | 8 |
57 | 39 | 9 |
58 | 3A | : |
59 | 3B | ; |
60 | 3C | < |
61 | 3D | = |
62 | 3E | > |
63 | 3F | ? |
64 | 40 | @ |
65 | 41 | A |
66 | 42 | B |
67 | 43 | C |
68 | 44 | D |
69 | 45 | E |
70 | 46 | F |
71 | 47 | G |
72 | 48 | H |
73 | 49 | I |
74 | 4A | J |
75 | 4B | K |
76 | 4C | L |
77 | 4D | M |
78 | 4E | N |
79 | 4F | O |
80 | 50 | P |
81 | 51 | Q |
82 | 52 | R |
83 | 53 | S |
84 | 54 | T |
85 | 55 | U |
86 | 56 | V |
87 | 57 | W |
88 | 58 | X |
89 | 59 | Y |
90 | 5A | Z |
91 | 5B | [ |
92 | 5C | \ |
93 | 5D | ] |
94 | 5E | ^ |
95 | 5F | _ |
96 | 60 | ` |
97 | 61 | a |
98 | 62 | b |
99 | 63 | c |
100 | 64 | d |
101 | 65 | e |
102 | 66 | f |
103 | 67 | g |
104 | 68 | h |
105 | 69 | i |
106 | 6A | j |
107 | 6B | k |
108 | 6C | l |
109 | 6D | m |
110 | 6E | n |
111 | 6F | o |
112 | 70 | p |
113 | 71 | q |
114 | 72 | r |
115 | 73 | s |
116 | 74 | t |
117 | 75 | u |
118 | 76 | v |
119 | 77 | w |
120 | 78 | x |
121 | 79 | y |
122 | 7A | z |
123 | 7B | { |
124 | 7C | | |
125 | 7D | } |
126 | 7E | ~ |
127 | 7F | DEL |


Callback Functions

Miscellaneous

Contents Callback Functions Example

A Callback Function is just a function that is automatically called at certain intervals during the execution of an action, typically so you can report on the action's progress. It's called a "callback function" because the action is said to be "calling back" to your function.

Callback Functions are mostly useful for actions that may take longer to complete. In those cases, it is nice to let the end user know what is happening so they don't start to worry. All actions that contain a callback function are automatically configured to pass the action's progress information to the built-in status dialog if the default value nil is passed as the CallbackFunction parameter. The status dialog can then be shown, hidden and manipulated using the available status dialog actions. Another purpose of the callback function is to provide the ability to interrupt the action's progress if required.

While using the status dialog may be the most common use of Callback Functions, there may be other tasks that need to be performed based on the progress of the action. In these cases you can create your own function to handle the action's progress in a custom way. Each Callback Function requires specific parameters to receive information from the action. Each action's callback parameters can be found in the action's help topic.

The following Setup Factory actions contain a Callback Function parameter:

  • File.Copy

  • File.Delete

  • File.Find

  • File.Install

  • File.Move

  • Folder.DeleteTree

  • Folder.Find

  • HTTP.Download

  • HTTP.DownloadSecure

  • HTTP.GetFileSize

  • HTTP.GetFileSizeSecure


INI Files

Miscellaneous

Contents INI Files

Initialization files, also known as INI files are commonly used as configuration files in Windows. In earlier versions of Windows, INI files were very common for storing both Windows and application settings. In more recent versions, Windows and applications have moved to using the Registry for storing configuration data. However INI files are still used for storing data and are very useful in some situations.

INI files are basically text files with the ".ini" file extension, making them very simple to work with, and view. These files are written in a specific format containing components called sections, keys, and values. Below is an example of the structure of an INI file:

[MyProduct]
InstallFolder=C:\MyFolder\ApplicationX
ProductKey=890765

[MyProduct] is the section of INI file, InstallFolder and ProductKey are keys and "C:\MyFolder\ApplicationX" and 890765 are key values.

The simple example above illustrates the structure of an INI file. Each INI file can contain any number of sections containing any number of keys and values, allowing you to store large amounts of configuration data.

Tip: Setup Factory contains a category of INI file actions that can be used to both create and modify INI files.


Input Mask

Miscellaneous

Contents Input Mask

An input mask is a special pattern that controls what the user can type into a MaskedInput dialog or edit field control at run time. The mask can be any combination of regular text characters, called "literals," and special characters, called "placeholders." Each placeholder represents one "place" in the edit field where the user can type a character. Different placeholders allow different kinds of characters to be typed in their "place" by the user. For example, the # placeholder only allows a digit between 0 and 9 to be typed in its place, and the ? placeholder only allows a letter between a and z.

Note: The placeholder characters you use in the input mask determine what the user will be allowed to type into the edit field.

You can use literals to include "normal" characters in the edit field. The user will type "around" the literal characters as they fill in the "blanks" created by the placeholders.

Here are the special characters that you can use in an input mask:
(Note that some of them are special literal characters that adapt to the user's system settings.)

. | Decimal placeholder. (Special literal.) This will be replaced by the character specified as the decimal placeholder in the user's international settings. To force a period on all systems, use \. instead.
, | Thousands separator. (Special literal.) This will be replaced by the character specified as the thousands separator in the user's international settings. To force a comma on all systems, use \, instead.
: | Time separator. (Special literal.) This will be replaced by the character specified as the time separator in the user's international settings. To force a colon on all systems, use \: instead.
/ | Date separator. (Special literal.) This will be replaced by the character specified as the date separator in the user's international settings. To force a slash on all systems, use \/ instead.
# | Digit placeholder (0-9). For every # in the input mask, the user will only be able to enter a digit between 0 and 9. To display a literal number sign (#), use \# instead.
A | Alphanumeric character placeholder (0-9 and a-Z). For every A in the input mask, the user will be able to enter any letter from a to z or any digit between 0 and 9. To display a literal "A", use \A instead.
? | Alphabetic placeholder (a-Z). For every ? in the input mask, the user will only be able to enter a letter from a to z. To display a literal question mark, use \? instead.
> | Alphabetic placeholder, but forces any letters typed to uppercase (A-Z). For every > in the input mask, the user will only be able to enter a letter from a to z, and whatever letter they type will be converted to uppercase. To display a literal greater-than sign, use \> instead.
< | Alphabetic placeholder, but forces any letters typed to lowercase (a-z). For every < in the input mask, the user will only be able to enter a letter from a to z, and whatever letter they type will be converted to lowercase. To display a literal less-than sign, use \< instead.
& | Character placeholder. Allows any ANSI character in the following ranges: 32-126 and 128-255. To display a literal ampersand, use \& instead.
\ | Literal escape. Use this to make a special character act as a literal in the input mask. For example, you could create a mask for an IP address: IP \Address\: ###\.###\.###\.### ...which would appear as: IP Address: . . . (Note that we needed to use the literal escape for the 'A' in Address, the colon, and all three decimal points.)


Language ID Codes

Miscellaneous

Contents Language ID Codes

Below is a list of the Windows operating system language ID codes:

Note: Any language that does not specify a secondary ID will return either 0x00, 0x01, or 0x02.

Primary ID Hex (Dec) | Secondary ID Hex (Dec) | Language
0x00 (0) | 0x00 (0) | Neutral
 | 0x01 (1) | User Default Sublanguage
 | 0x02 (2) | System Default
 | 0x03 (3) | Default Custom Sublanguage
 | 0x04 (4) | Unspecified Custom Sublanguage
 | 0x05 (5) | Default Custom MUI Sublanguage
0x01 (1) | 0x01 (1) | Arabic (Saudi Arabia)
 | 0x02 (2) | Arabic (Iraq)
 | 0x03 (3) | Arabic (Egypt)
 | 0x04 (4) | Arabic (Libya)
 | 0x05 (5) | Arabic (Algeria)
 | 0x06 (6) | Arabic (Morocco)
 | 0x07 (7) | Arabic (Tunisia)
 | 0x08 (8) | Arabic (Oman)
 | 0x09 (9) | Arabic (Yemen)
 | 0x0a (10) | Arabic (Syria)
 | 0x0b (11) | Arabic (Jordan)
 | 0x0c (12) | Arabic (Lebanon)
 | 0x0d (13) | Arabic (Kuwait)
 | 0x0e (14) | Arabic (U.A.E.)
 | 0x0f (15) | Arabic (Bahrain)
 | 0x10 (16) | Arabic (Qatar)
0x02 (2) |  | Bulgarian (Bulgaria)
0x03 (3) |  | Catalan (Spain)
0x04 (4) | 0x01 (1) | Chinese (Traditional)
 | 0x02 (2) | Chinese (Simplified)
 | 0x03 (3) | Chinese (Hong Kong SAR, PRC)
 | 0x04 (4) | Chinese (Singapore)
 | 0x05 (5) | Chinese (Macau SAR)
0x05 (5) |  | Czech (Czech Republic)
0x06 (6) |  | Danish (Denmark)
0x07 (7) | 0x01 (1) | German (Germany)
 | 0x02 (2) | German (Switzerland)
 | 0x03 (3) | German (Austrian)
 | 0x04 (4) | German (Luxembourg)
 | 0x05 (5) | German (Liechtenstein)
0x08 (8) |  | Greek (Greece)
0x09 (9) | 0x01 (1) | English (US)
 | 0x02 (2) | English (UK)
 | 0x03 (3) | English (Australian)
 | 0x04 (4) | English (Canadian)
 | 0x05 (5) | English (New Zealand)
 | 0x06 (6) | English (Ireland)
 | 0x07 (7) | English (South Africa)
 | 0x08 (8) | English (Jamaica)
 | 0x09 (9) | English (Caribbean)
 | 0x0a (10) | English (Belize)
 | 0x0b (11) | English (Trinidad and Tobago)
 | 0x0c (12) | English (Zimbabwe)
 | 0x0d (13) | English (Philippines)
 | 0x10 (16) | English (India)
 | 0x11 (17) | English (Malaysia)
 | 0x12 (18) | English (Singapore)
0x0a (10) | 0x01 (1) | Spanish (Spain, Traditional Sort)
0 | 0x02 (2) | Spanish (Mexico)
0 | 0x03 (3) | Spanish (Spain, Modern Sort)
0 | 0x04 (4) | Spanish (Guatemala)
0 | 0x05 (5) | Spanish (Costa Rica)
0 | 0x06 (6) | Spanish (Panama)
0 | 0x07 (7) | Spanish (Dominican Republic)
0 | 0x08 (8) | Spanish (Venezuela)
0 | 0x09 (9) | Spanish (Colombia)
0 | 0x0a (10) | Spanish (Peru)
0 | 0x0b (11) | Spanish (Argentina)
0 | 0x0c (12) | Spanish (Ecuador)
0 | 0x0d (13) | Spanish (Chile)
0 | 0x0e (14) | Spanish (Uruguay)
0 | 0x0f (15) | Spanish (Paraguay)
0 | 0x10 (16) | Spanish (Bolivia)
0 | 0x11 (17) | Spanish (El Salvador)
0 | 0x12 (18) | Spanish (Honduras)
0 | 0x13 (19) | Spanish (Nicaragua)
0 | 0x14 (20) | Spanish (Puerto Rico)
0x0b (11) |  | Finnish (Finland)
0x0c (12) | 0x01 (1) | French (France)
 | 0x02 (2) | French (Belgian)
 | 0x03 (3) | French (Canadian)
 | 0x04 (4) | French (Swiss)
 | 0x05 (5) | French (Luxembourg)
 | 0x06 (6) | French (Monaco)
0x0d (13) |  | Hebrew (Israel )
0x0e (14) |  | Hungarian (Hungary)
0x0f (15) |  | Icelandic (Iceland)
0x10 (16) | 0x01 (1) | Italian (Italy)
 | 0x02 (2) | Italian (Switzerland)
0x11 (17) |  | Japanese (Japan)
0x12 (18) | 0x01 (1) | Korean (Korea)
0x13 (19) | 0x01 (1) | Dutch (Netherlands)
 | 0x02 (2) | Dutch (Belgian)
0x14 (20) | 0x01 (1) | Norwegian (Bokmal)
 | 0x02 (2) | Norwegian (Nynorsk)
0x15 (21) |  | Polish (Poland)
0x16 (22) | 0x01 (1) | Portuguese (Brazil)
 | 0x02 (2) | Portuguese (Portugal)
0x17 (23) |  | Romansh (Switzerland)
0x18 (24) |  | Romanian (Romania)
0x19 (25) |  | Russian (Russia)
0x1a (26) | 0x01 (1) | Croatian (Croatia)
 | 0x04 (4) | Croatian (Bosnia and Herzegovina, Latin)
0x1a (26) | 0x02 (2) | Serbian (Latin)
 | 0x03 (3) | Serbian (Cyrillic)
 | 0x06 (6) | Serbian (Bosnia and Herzegovina, Latin)
 | 0x07 (7) | Serbian (Bosnia and Herzegovina, Cyrillic)
0x1b (27) |  | Slovak (Slovakia)
0x1c (28) |  | Albanian (Albania)
0x1d (29) | 0x01 (1) | Swedish (Sweden)
 | 0x02 (2) | Swedish (Finland)
0x1e (30) |  | Thai (Thailand)
0x1f (31) |  | Turkish (Turkey)
0x20 (32) | 0x01 (1) | Urdu (Pakistan)
 | 0x02 (2) | Urdu (India)
0x21 (33) |  | Indonesian (Indonesia)
0x22 (34) |  | Ukrainian (Ukraine)
0x23 (35) |  | Belarusian (Belarus)
0x24 (36) |  | Slovenian (Slovenia)
0x25 (37) |  | Estonian (Estonia)
0x26 (38) |  | Latvian (Latvia)
0x27 (39) | 0x01 (1) | Lithuanian (Lithuanian)
0x28 (40) |  | Tajik (Tajikistan, Cyrillic)
0x29 (41) |  | Persian (Iran), previously Farsi
0x2a (42) |  | Vietnamese (Vietnam)
0x2b (43) |  | Armenian (Armenia)
0x2c (44) | 0x01 (1) | Azeri (Latin)
 | 0x02 (2) | Azeri (Cyrillic)
0x2d (45) |  | Basque (Basque)
0x2E (46) | 0x01 (1) | Upper Sorbian (Germany)
 | 0x02 (2) | Lower Sorbian (Germany)
0x2f (47) |  | Macedonian (Macedonia, FYROM)
0x32 (50) |  | Setswana (South Africa)
0x34 (52) |  | isiXhosa (South Africa)
0x35 (53) |  | isiZulu (South Africa)
0x36 (54) |  | Afrikaans (South Africa)
0x37 (55) |  | Georgian (Georgia)
0x38 (56) |  | Faeroese (Faroe Islands)
0x39 (57) |  | Hindi (India)
0x3A (58) |  | Maltese (Malta)
0x3B (59) | 0x01 (1) | Sami (Northern, Norway)
 | 0x02 (2) | Sami (Northern, Sweden)
 | 0x03 (3) | Sami (Northern, Finland)
 | 0x04 (4) | Sami (Lule, Norway)
 | 0x05 (5) | Sami (Lule, Sweden)
 | 0x06 (6) | Sami (Southern, Norway)
 | 0x07 (7) | Sami (Southern, Sweden)
 | 0x08 (8) | Sami (Skolt, Finland)
 | 0x09 (9) | Sami (Inari, Finland)
0x3C (60) |  | Irish (Ireland)
0x3e (62) | 0x01 (1) | Malay (Malaysia)
 | 0x02 (2) | Malay (Brunei Darassalam)
0x3f (63) |  | Kazakh (Kazakhstan)
0x40 (64) |  | Kyrgyz (Kyrgyzstan)
0x41 (65) |  | Swahili (Kenya)
0x42 (66) |  | Turkmen (Turkmenistan)
0x43 (67) | 0x01 (1) | Uzbek (Latin)
 | 0x02 (2) | Uzbek (Cyrillic)
0x44 (68) |  | Tatar (Russia)
0x45 (69) | 0x01 (1) | Bengali (India)
 | 0x02 (2) | Bengali (Bangladesh)
0x46 (70) |  | Punjabi (India)
0x47 (71) |  | Gujarati (India)
0x48 (72) |  | Oriya (India)
0x49 (73) |  | Tamil (India)
0x4a (74) |  | Telugu (India)
0x4b (75) |  | Kannada (India)
0x4c (76) |  | Malayalam (India)
0x4d (77) |  | Assamese (India)
0x4e (78) |  | Marathi (India)
0x4f (79) |  | Sanskrit (India)
0x50 (80) | 0x01 (1) | Mongolian (Mongolia, Cyrillic)
 | 0x02 (2) | Mongolian (Mongolia, Mong)
0x51 (81) |  | Tibetan (PRC)
0x52 (82) |  | Welsh (United Kingdom)
0x53 (83) |  | Khmer (Cambodia)
0x54 (84) |  | Lao (Lao PDR)
0x56 (86) |  | Galician (Spain)
0x57 (87) |  | Konkani (India)
0x58 (88) |  | Manipuri
0x59 (89) |  | Sindhi
0x5a (90) |  | Syriac (Syria)
0x5B (91) |  | Sinhala (Sri Lanka)
0x5D (93) | 0x01 (1) | Inuktitut (Canada)
 | 0x02 (2) | Inuktitut (Canada, Latin)
0x5E (94) |  | Amharic (Ethiopia)
0x5F (95) |  | Tamazight (Algeria, Latin)
0x60 (96) |  | Kashmiri
0x61 (97) | 0x01 (1) | Nepali (Nepal)
 | 0x02 (2) | Nepali (India)
0x62 (98) |  | Frisian (Netherlands)
0x63 (99) |  | Pashto (Afghanistan)
0x64 (100) |  | Filipino (Philippines)
0x65 (101) |  | Divehi (Maldives)
0x68 (104) |  | Hausa (Nigeria)
0x6A (106) |  | Yoruba (Nigeria)
0x6B (107) | 0x01 (1) | Quechua (Bolivia)
 | 0x02 (2) | Quechua (Ecuador)
 | 0x03 (3) | Quechua (Peru)
0x6C (108) |  | Sesotho sa Leboa (South Africa)
0x6D (109) |  | Bashkir (Russia)
0x6E (110) |  | Luxembourgish (Luxembourg)
0x6F (111) |  | Greenlandic (Greenland)
0x70 (112) |  | Igbo (Nigeria)
0x73 (115) |  | Tigrigna
0x78 (120) |  | Yi (PRC)
0x7A (122) |  | Mapudungun (Chile)
0x7C (124) |  | Mohawk (Canada)
0x7E (126) |  | Breton (France)
0x7F (127) |  | Invariant Sublanguage
0x80 (128) |  | Uyghur (PRC)
0x81 (129) |  | Maori (New Zealand)
0x82 (130) |  | Occitan (France)
0x83 (131) |  | Corsican (France)
0x84 (132) |  | Alsatian (France)
0x85 (133) |  | Yakut (Russia)
0x86 (134) |  | K'iche (Guatemala)
0x87 (135) |  | Kinyarwanda (Rwanda)
0x88 (136) |  | Wolof (Senegal)
0x8C (140) |  | Dari (Afghanistan)


Quad-State Check Box

Overview

Quad-state check boxes are used in Setup Factory when editing the properties of multiple items at once that exist in a tree view structure, such as the conditions of files or folder references. Each state represents a specific action that will be taken on the property for all of the items it is applied to. In a tree structure, some states also affect the states of other check boxes in the tree.

As its name implies, a quad-state check box contains four distinct states. These four states are as follows:

Checked ( )

When the check box is checked, it means that the current property is being selected for all of the selected items, overriding all previous settings for this property. If the tree value's checkbox is a parent containing children, all of its children's properties will be selected as well.

If the tree value's checkbox is a child with siblings, whose states are different, this will cause its parent to change to the Mixed state.

Unchecked ( )

When the check box is unchecked, it means that the current property is being removed for all of the selected items, overriding all previous settings for this property. If the tree value's checkbox is a parent containing children, all of its children's properties will be unchecked as well.

If the tree value's checkbox is a child with siblings, whose states are different, this will cause its parent to change to the Mixed state.

Indeterminate ( )

When the check box is in the indeterminate state, it means that the current property for the selected files are a mixture of checked and unchecked values and their current states should be preserved.

If the tree value's checkbox is a child with siblings, whose states are different, this will cause its parent to change to the Mixed state.

Mixed ( )

When a checkbox is in the mixed state, it means that the current property contains children whose states are different.


System Restore Monitored File Extensions

Miscellaneous

Contents System Restore Monitored File Extensions

The following is a list of monitored file extensions. Files with these extensions are monitored by System Restore:

~~C

~~D

12A

1PA

1ST

386

8BA

8BY

8LI

A2A

AAS

AAX

ABM

ABR

ACF

ACG

ACO

ACS

ADK

ADW

ADX

AFM

AID

AIP

ALT

AM

AMB

APL

APM

APP

APV

AR

ARX

AS

AT

ATC

ATL

ATM

ATN

AW

AWE

AWX

AX

B0

BAT

BCF

BD

BDR

BE

BGB

BGR

BID

BIT

BK1

BLD

BM

BMA

BND

BNF

BOF

BPP

BPT

BPX

BT

BTN

BUC

CAG

CAO

CAT

CBS

CC

CF

CFG

CHA

CIK

CL

CLW

CLX

CLY

CMD

CNT

CNV

COL

COM

CPB

CPL

CQM

CR

CRL

CRS

CRV

CS

CSB

CSI

CSL

CSW

CTB

CTG

CTY

CUS

CW_

D01

D02

D03

D04

D05

D32

DATA

DB0

DB1

DB2

DC2

DCA

DCF

DCI

DCL

DDB

DDD

DEP

DES

DESKLINK

DET

DGM

DIALOG

DID

DIR

DISABLED

DIX

DLL

DOB

DOS

DRC

DRS

DRV

DS

DSC

DSK

DSN

DSR

DSX

DT

DTT

DUN

DVB

DWT

DXT

DYNCMD

ECF

EFF

EFM

EID

EL

ELM

END

ENU

ENV

EOT

EPF

ET

EX_

EXA

EXCLUDE

EXE

EXL

F32

FAE

FAM

FAS

FFP

FIN

FIO

FLL

FLW

FMC

FMP

FNT

FON

FSG

FSS

GCS

GDB

GI_

GMS

GNG

GPD

GS

GSF

GST

GUIATN

GUICMD

GVT

GWD

H16

HCT

HDC

HDI

HDP

HFX

HGD

HHC

HHK

HK0

HK1

HK2

HK3

HLP

HM

HTA

HTC

HTZ

HU

HWL

HYP

IAT

IBD

ICD

ICM

ICO

ICR

ICW

ID

IDS

IFA

ILF

ILG

ILM

IN_

INCL

INF

INI

INK

INL

INO

INS

INV

IP

IRS

ISA

ISS

ISU

ITF

J0

JA

JBR

JCM

JGD

K01

K02

K03

KBD

KNN

KO

L0

L2L

L2P

LAB

LAM

LAST

LCA

LCK

LDA

LEX

LGC

LGD

LGE

LGF

LIC

LID

LIM

LIVEREG

LLI

LMC

LMG

LMP

LNK

LO~

LRD

LRS

LSM

LSO

LSQ

LSS

LSX

LT

LTS

LV

M20

MANIFEST

MAPIMAIL

MC

MCD

MCM

MD2

MDM

MDP

ME

MFL

MHK

MIL

MLN

MMC

MMM

MMX

MNC

MNL

MNR

MNS

MOF

MOR

MP

MPD

MPT

MSB

MSC

MSE

MSI

MST

MSK

MSO

MXT

MYDOCS

N0

NAM

NAME

NDX

NEW

NFO

NIB

NMD

NOD

NPM

NQM

NQV

NSI

NSW

NTE

NU4

NUM

NUS

NV

OBE

OCM

OCX

ODE

ODL

OLB

OLD

OLE

OP

OPG

OR5

OSD

OUT

P2A

PAG

PBC

PBK

PBV

PC3

PCI

PDI

PDR

PEN

PER

PFB

PFM

PFR

PH

PHO

PHX

PID

PIF

PL3

PLY

PMT

PNF

POC

POF

POL

PPD

PR4

PROPERTIES

PRX

PSC

PSF

PSP

PT

PTH

PTX

PV

Q0

Q32

Q3X

QDAT

QJF

QRS

QTC

QTD

QTW

QUE

QUF

QUT

R0

R98

RAD

RAT

RC2

RCP

RCT

RDB

RDC

REF

REG

RGS

RH

RI

RJS

RO

ROB

RPR

RPS

RSD

RSP

RSRC

RTA

RTR

RU

S98

SAM

SAX

SCK

SCR

SCS

SECURITY

SELFREG

SFP

SG

SG0

SG1

SHARED

SHR

SHX

SIF

SK

SLL

SMC

SMM

SNP

SOF

SPC

SPE

SPM

SPT

SPX

SR

SRC

SRG

SRT

SSM

SST

ST4

STB

STD

STF

STP

SWB

SYM

SYN

SYS

T32

TAG

TB

TDF

TH

THE

THK

THS

TID

TIE

TIP

TLB

TLD

TLF

TLT

TLU

TLX

TMC

TNL

TOL

TPA

TR

TRE

TRG

TRO

TSK

TSP

TTF

TTS

TUB

TUM

TUW

TV

TVC

TWD

TXR

TYM

TZD

UBM

UCM

UCP

UCT

UDC

UDI

UDL

UDT

UID

UIL

UK

ULG

ULK

UNT

US

USA

USERPROFILE

USP

USR

UTX

V10

VBS

VBX

VBZ

VCPREF

VDB

VER

VFM

VFX

VIL

VLX

VM

VOF

VPH

VPX

VQA

VQM

VSC

VSH

VWP

VXD

W32

W98

WA_

WBD

WBM

WCD

WDL

WDS

WINSYS

WIPEINFO

WIPESLACK

WMZ

WPC

WPX

WRF

WSL

WTB

WTR

XLL

XMX

XRS

XTU

ZFSENDTOTARGET

ZH

ZH_TW

ZRW


Tri-State Check Box

Overview

Tri-state check boxes are used in Setup Factory when editing the properties of multiple items at once, such as the properties of a file or folder reference. Each state represents a specific action that will be taken on the property for all of the items it is applied to.

As its name implies, a tri-state check box contains three distinct states. These three states are as follows:

Checked ( )

When the check box is checked, this means that the current property is being selected for all of the selected items, overriding all previous settings for this property.

Unchecked ( )

When the check box is unchecked, this means that the current property is being removed for all of the selected items, overriding all previous settings for this property.

Indeterminate ( )

When the check box is in the indeterminate state, this means that the current property for the selected files are a mixture of checked and unchecked values and their current states should be preserved.


Virtual Key Codes

Miscellaneous

Contents Virtual Key Codes

Virtual key codes provide a hardware and language-independent method of identifying keyboard keys. The following table contains the list of key codes that you can use to identify what key was pressed.

Decimal | Hex | Character
8 | 8 | Backspace
9 | 9 | Tab
13 | D | Enter
16 | 10 | Shift (both)
17 | 11 | Ctrl (both)
19 | 13 | Pause
20 | 14 | Caps Lock
27 | 1B | Esc
32 | 20 | Spacebar
33 | 21 | Page Up
34 | 22 | Page Down
35 | 23 | End
36 | 24 | Home
37 | 25 | (left arrow)
38 | 26 | (up arrow)
39 | 27 | (right arrow)
40 | 28 | (down arrow)
45 | 2D | Insert
46 | 2E | Delete
48 | 30 | 0
49 | 31 | 1
50 | 32 | 2
51 | 33 | 3
52 | 34 | 4
53 | 35 | 5
54 | 36 | 6
55 | 37 | 7
56 | 38 | 8
57 | 39 | 9
65 | 41 | A or a
66 | 42 | B or b
67 | 43 | C or c
68 | 44 | D or d
69 | 45 | E or e
70 | 46 | F or f
71 | 47 | G or g
72 | 48 | H or h
73 | 49 | I or i
74 | 4A | J or j
75 | 4B | K or k
76 | 4C | L or l
77 | 4D | M or m
78 | 4E | N or n
79 | 4F | O or o
80 | 50 | P or p
81 | 51 | Q or q
82 | 52 | R or r
83 | 53 | S or s
84 | 54 | T or t
85 | 55 | U or u
86 | 56 | V or v
87 | 57 | W or w
88 | 58 | X or x
89 | 59 | Y or y
90 | 5A | Z or z
91 | 5B | (left Windows key)
92 | 5C | (right Windows key)
93 | 5D | (application key - located between the right Windows and Ctrl keys on most keyboards)
96 | 60 | 0 (numpad with Num Lock on)
97 | 61 | 1 (numpad with Num Lock on)
98 | 62 | 2 (numpad with Num Lock on)
99 | 63 | 3 (numpad with Num Lock on)
100 | 64 | 4 (numpad with Num Lock on)
101 | 65 | 5 (numpad with Num Lock on)
102 | 66 | 6 (numpad with Num Lock on)
103 | 67 | 7 (numpad with Num Lock on)
104 | 68 | 8 (numpad with Num Lock on)
105 | 69 | 9 (numpad with Num Lock on)
106 | 6A | * (numpad)
107 | 6B | + (numpad)
109 | 6D | - (numpad)
110 | 6E | . (numpad)
111 | 6F | / (numpad)
112 | 70 | F1
113 | 71 | F2
114 | 72 | F3
115 | 73 | F4
116 | 74 | F5
117 | 75 | F6
118 | 76 | F7
119 | 77 | F8
120 | 78 | F9
122 | 7A | F11
123 | 7B | F12
144 | 90 | Num Lock
145 | 91 | Scroll Lock
186 | BA | ;
187 | BB | =
188 | BC | ,
189 | BD | -
190 | BE | .
191 | BF | /
192 | C0 | `
219 | DB | [
220 | DC | \
221 | DD | ]
222 | DE | '


XML Actions Concepts

Contents Overview

Description

The XML actions allow you to efficiently and effectively work with any valid XML (Extensible Markup Language) file.

We've made the XML actions extremely powerful, yet remarkably easy to use. Using an innovative XML referencing scheme which we've named "XML Paths," these actions make reading, writing and manipulating XML files simple and straightforward.

If you need to work with XML data, these actions are for you.

XML Paths

Many of the XML actions contain a parameter called XMLPath. This path is used to locate a specific element in the XML file. For example, in the sample XML document, the "address" element inside the first "customer" element can be accessed using:

database/customer/address_info/address

Since an XML document can contain multiple elements with the same name, you often cannot access every element in a document by name alone. For example, what if you need to access the information in the second customer element?

The secret is to add an optional index to each element name in order to specify which occurrence of that name the path refers to. In XML paths, an index consists of a single colon (:) followed by a number. (If no index is specified, the index is assumed to be 1.)

For example, to access the second "customer" element in the first "database" element of the sample XML document, you could use:

database/customer:2

As another example, to access the second "phone" element in the second "customer" element, you would use:

database/customer:2/phone:2

Matching Any Element Name

An asterisk (*) can be used in an XML path to find the first matching element at a given level.

For example, you can use paths like this:

*/customer

...which refers to the first customer element in the first root element, no matter what the root element is named. In other words, the above path wouldn't care whether the root element was "database" or "moonbase_alpha."

You can use an asterisk with an index to refer to an element by position instead of by name. For example, you could use the following path to access the second element inside the customer element, no matter what that element is named:

database/customer/*:2

Using the above path, it wouldn't matter what the first two elements inside customer were named; they could be "first_name" and "last_name" or they could be "nose_length" and "hair_color"...either way, it would be the second element that would be referenced.

You can even form a path with nothing but asterisks. For example, the following path would refer to the third child element within the second root element:

*:2/*:3

Note: An asterisk always matches a single element. It doesn't match "all" elements at that level.

Using a Different Index Delimiter

If you need to, you can change the index delimiter from ':' to something else by assigning a different value to the special Lua variable XML.Delimiter. For example, if your XML document has element names with ':' characters in them, you could change the delimiter to '|' instead by using this script:

XML.Delimiter = "|";

...after which you would specify paths like this:

database/customer|2/phone|2

Sample XML

Note: Most of the examples assume the following XML to be already loaded into memory. To test the examples you can save the text below as an .xml file and then use an XML.Load action to load it into memory.

<database>
<customer id="1010" product="AutoPlay">
<first_name>John</first_name>
<last_name>Smith</last_name>
<company>Indigo Rose</company>
<address_info>
<address>100 Mystreet</address>
<city>Winnipeg</city>
<province>Manitoba</province>
<country>Canada</country>
<postal_code>R3B 0R3</postal_code>
</address_info>
<phone location="daytime">(204)946-0263</phone>
<phone location="evening">(204)946-0242</phone>
<fax>(204)942-3421</fax>
<email>sales@indigorose.com</email>
</customer>
<customer id="1040" product="Setup Factory">
<first_name>Sara</first_name>
<last_name>Winters</last_name>
<company>Indigo Rose</company>
<address_info>
<address>200 Secondstreet</address>
<city>Winnipeg</city>
<province>Manitoba</province>
<country>Canada</country>
<postal_code>R3B 0R4</postal_code>
</address_info>
<phone location="daytime">(204)946-0244</phone>
<phone location="evening">(204)946-0289</phone>
<fax>(204)942-3422</fax>
<email>sales@indigorose.com</email>
</customer>
</database>

The following XML actions are available:

XML.Count
XML.GetAttribute
XML.GetAttributeNames
XML.GetElementNames
XML.GetElementXML
XML.GetValue
XML.GetXML
XML.InsertXML
XML.Load
XML.RemoveAttribute
XML.RemoveElement
XML.Save
XML.SetAttribute
XML.SetValue
XML.SetXML


Installing on Windows Vista or Later

Windows Vista

Overview

In general installs and applications designed for Windows XP are highly compatible with Windows Vista or later given its file, folder and registry virtualization features. Many of Windows XP's existing features have been enhanced and new features added. While there is a high compatibility, new features and the tightening of security require developers to be aware of certain changes that affect both application development and distribution.

Important Vista Features

User Account Control (UAC)

By default, in Windows XP all user accounts were created as local administrators. This meant that many users ran as administrators with full access privileges leaving the security of the system open to attacks. A design goal of the UAC was to prevent installations from being executed without the user's knowledge. While user accounts and restricted tokens have been around in previous versions of Windows, Windows Vista and later contains security protection for the administrator account as well. When an administrator logs in, two different tokens are created. The first token grants all the permissions and privileges of the administrator, while the second token is a restricted token (filtered token), offering virtually the same privileges of a standard user. With UAC (User Account Control) enabled, members of the administrators group run with the same access token as standard users. Only when the user gives approval will the program be granted the full access token.

Note: Features of UAC can be enabled and disabled, so developers should not rely on its features for elevation.

Application Manifests

While application manifests are not new to Windows Vista or later, a new section has been added for the UAC to mark applications with a requested execution level. This information notifies the operating system of the privileges that the application requires so it can perform any necessary elevation. All UAC compliant applications should have the requested execution level added to its application manifest. Applications that are not run elevated or are not detected by Windows Vista's installer detection, may be run with file and registry virtualization (see next section). In future releases of Windows, the only way to run an application elevated will to have a signed manifest identifying the required privilege level.

File/Registry Virtualization

In an attempt to provide compatibility for applications that are not UAC compliant, Windows Vista or later contains a new virtualization technology for files, folders and the registry. When a non-UAC compliant application tries to write to a protected directory such as Program Files, or a global portion of the registry such as HKEY_LOCAL_MACHINE\Software, the application is provided with a virtualized copy that is stored under the user's profile. Developers are not to rely on this technology being present in the future.

Virtualization (file/registry) is turned OFF for any applications:

  • Containing an application manifest with an appropriate requested execution level.

  • Detected by Windows Vista or later as installation programs resulting in a prompt for elevation/approval.

  • That are run elevated.

  • 64-bit processes.

Setup Factory Vista/Windows 7/Windows 8/Windows 8.1/Windows 10 Runtime Features

Several features have been added to aid in the installation process on Windows Vista or later. Additional features will be added in future service releases.

  • Windows Vista/Windows 7/Windows 8/Windows 8.1/Windows 10 system requirement checkbox found in Project > System Requirements.

  • Windows Vista/Windows 7/Windows 8/Windows 8.1/Windows 10 single and multiple file install conditions found on the Conditions tab of the single or multiple file/folder reference properties dialog.

  • Setup application manifests containing configurable requested execution level settings. The Requested User Privilege Level setting can be found in Project > Advanced Settings.

  • Support added to the System.GetOSName and System.GetOSVersionInfo actions.

  • New return code for the File.Run action pertaining to elevation being required.

  • Support (and additional table item) added to the System.GetUserInfo action regarding administrator detection.

  • New action System.GetOSProductInfo that can be used to get the product type of Windows Vista/Windows 7/Server 2008/Server 2008 R2/Windows 8/Windows Server 2012/Windows 8.1/Windows Server 2012 R2/Windows 10/Windows Server 10 operating systems.

  • Addition of a "WaitForReturn" parameter and return code support for the Shell.Execute action.

  • Integrated Authenticode Code Signing to allow you to code sign your setups and uninstall with your certificate. You can find these settings on the Code Signing tab of the "Build Settings" dialog (Publish > Settings).

  • An option called Collect launch user information found on the "Setup File" tab of Publish > Settings that populates a series of session variables with the folders located in the user profile that launched the setup. The following variables are available: %LaunchUserApplicationDataFolder%, %LaunchUserDesktopFolder%, %LaunchUserMyDocumentsFolder%, %LaunchUserMyMusicFolder%, %LaunchUserMyPicturesFolder%, %LaunchUserMyVideosFolder%, %LaunchUserStartFolder%, %LaunchUserStartProgramsFolder%, %LaunchUserStartupFolder%.

Changing the "Requested User Privilege Level" Setting

The Requested User Privilege Level setting specifies which requested execution level to include in the install/uninstall's application manifest for distribution on Windows Vista or later. When the installation is run, the operating system reads this information to identify what privileges the installation requires. The default setting in Setup Factory is "Require administrator" and should generally never be changed. If for some reason you do not want to require administrator privileges to run the setup given the content of your install, you should be aware of the following information and required changes:

Important Note: The "Requested User Privilege Level" setting is only effective if the user has UAC enabled. Each user's UAC settings can also be configured differently, so you should not rely solely on this feature. When performing administrative tasks, you should always include administrator checks using the System.GetUserInfo action's "IsAdmin" and "IsVistaAdminLimitedToken" table return values. Windows Vista or later operating system detection can also be achieved using the System.GetOSName and System.GetOSVersionInfo actions.

Changing to "As invoker"

Using the "As invoker" setting means that your setup does not require any system access other than the current user's profile areas. Many of these issues exist for previous versions of Windows when running the setup as a standard user.

Important information requiring attention:

Running Programs

User Account Control (UAC) On

Problem: File.Run actions will fail for both standard users and Administrator users if Windows Vista or later identifies the target file as requiring elevation. This will happen for files containing marked application manifests requiring elevation, or detected by Windows Vista's installer detection.

Solutions: If the target file contains a proper manifest, and contains its own Administrator detection and notification, or is an install/patch/update that Vista or later will detect with its installer detection feature, use the Shell.Execute action instead. This will allow Vista or later to prompt for approval or login credentials. The second solution is to mark your setup as "Require administrator". In addition, you should always perform any required Administrator detection using the System.GetUserInfo action. This will enable you to determine if the user is an administrator running with full privileges, or if they are part of the administrators group, but running with limited privileges.

User Account Control (UAC) Off

When User Account Control (UAC) has been disabled on the system, the permission rules for running programs are the same as they are on other NT based operating systems such as Windows XP. Both the File.Run and Shell.Execute actions will succeed, however the target application will be subject to the privileges of the current user. Again, you should always perform any required Administrator detection using the System.GetUserInfo action and respond appropriately.

File system modifications

Certain locations are only accessible to users with administrative privileges such as: C:\Windows, C:\Windows\System32, Program Files and any files that are part of the Windows Resource Protection (WRP). Windows Vista or later also prevents files from being written to the root of the C:. When UAC is On, both standard user accounts and users that are members of the Administrators group will fail. When UAC is Off, only members of the Administrators group will succeed. This affects actions such as File.Copy, File.Install, System.RegisterActiveX etc.

Log File (install/uninstall)

By default, the setup log file is created in the Windows folder. This folder generally cannot be accessed by a user (all users initially) assigned the standard user access token. Therefore this path must be changed to a per-user writable location such as the user's Documents folder, or Application Data.

Uninstall

By default, the uninstall executable is written to the non-accessible Windows folder. This must be changed to a writable per-user location such as Application Data.

Note: The uninstall control panel entry is written to a location under the HKEY_LOCAL_MACHINE registry key and will fail when attempted as a user with the standard user access token. This feature must be disabled if you choose to change the manifest to "As Invoker."

Registry modifications

Generally standard users only contain write access to locations under HKEY_CURRENT_USER. When UAC is On, both standard user accounts and users that are members of the Administrators group will fail if you try to write to another location. When UAC is Off, only members of the Administrators group will succeed.

Changing to "Highest available"

Using the "Highest available" setting means that your setup is designed to be run by all users. The setup runs with the same access token as the parent process. This means that if the setup is run by a member of the Administrators group, their privileges will be elevated to the Administrator's full access token when given their consent. However, this also means that if a standard user ran the setup, they would only have their highest privileges, those being a standard user. Therefore all issues mentioned above for "As invoker" would exist using this setting resulting in possible application failure. Again, if your setup performs administrator tasks, the "Require administrator" option should be used in addition to the usual administrator detection and conditions.

Previously Created Setups

Setup Factory's Vista compatibility was implemented in the 7.0.6.0 service release. Setups are now properly manifested using the Requested User Privilege Level setting. Installs created using a previous service release may encounter some compatibility problems. However, Windows Vista contains a new "Installer Detection" feature that automatically detects unmanifested Setup Factory setups as installations. This will automatically prompt the user for elevation or logon credentials.

Note: While the Windows Vista "Detect application installation and prompt for elevation" setting is enabled by default, it can be turned off. If this setting was disabled, the setup would be subject to file, folder and registry virtualization when writing to protected areas that may cause application failure. While this feature was designed to increase application compatibility, the possibility for error does exist. If you wish for your setups to be Windows Vista compliant, we strongly recommend publishing the setup again using in the current version of Setup Factory.

Authenticode Signing

The goal of Authenticode signing is to ensure both the integrity and authenticity of the program. If you plan to distribute on Windows Vista or later, another point of consideration beyond user experience, is the fact that it has the ability to prevent any unsigned application from launching with full privileges. This may impact both the install and application functionality. It is recommended that all application and setup files be signed when distributed on Windows Vista or later.

Note: For more information, see Authenticode Code Signing.


Authenticode Code Signing

Overview

Using Authenticode Code Signing

Background

How can users trust code that is published on the Internet? Two issues that must be addressed are those of ensuring integrity and authenticity. Authenticity assures users that they know where the code came from. Integrity verifies that the code hasn't been tampered with since its publication.

In the Microsoft article titled Introduction to Code Signing, they write:

Microsoft's solution to these issues is Microsoft Authenticode coupled with an infrastructure of trusted entities. Authenticode, which is based on industry standards, allows developers to include information about themselves and their code with their programs through the use of digital signatures.

While Authenticode itself cannot guarantee that signed code is safe to run, Authenticode is the mechanism by which users can be informed of whether the software publisher is participating in the infrastructure of trusted entities. Thus, Authenticode serves the needs of both software publishers and users who rely upon the Internet for the downloading of software.

Why Should I Care?

If you plan to distribute your software over the Internet and you expect that some of your users will be using Windows XP Service Pack 2, Windows Vista or later you may want to consider signing your setups. Due to the changes made to Internet Explorer in Windows XP SP2, and the Windows Vista or later OS's, when a customer downloads and runs your software, they will be presented with a warning dialog asking the user if they really want to run your software. On that dialog, they will see "Unknown Publisher" if it is not signed. On the other hand, if you do sign your code, they will instead see your company name and an optional web link to follow for more information. If you plan to distribute on Windows Vista or later, another point of consideration beyond user experience, is the fact that Windows Vista or later has the ability to prevent any unsigned applications from launching with full privileges. This may impact both the installing and application functionality.

Getting a Code Signing Certificate

If you would like to purchase a code signing certificate, they are available from a number of companies, including Verisign, Thawte and Comodo.

During the purchase process, you will be instructed on creating and saving a "private key" file, which will later be used along with your certificate to actually "sign" your software. You will also be asked for a password to protect your private key. Do not misplace any of this information. Each piece is extremely important!

It will take about 3-5 days for your application to be approved and your certificate issued. Keep in mind that you will likely need to provide supporting documentation to prove you actually are who you say you are. It's not something to be taken lightly and will likely require senior management to be involved.

Download SignCode.exe or SignTool.exe

Now that you have a code signing certificate, you'll need to download some software from Microsoft so you can start using it.

  1. The current tool available from Microsoft to digitally sign files is called "SignTool.exe". This tool is installed in the \Bin folder of the Platform Software Development Kit (SDK). You can download the Platform SDK from: http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5
    The tool previous to signtool.exe available for signing files was called "SignCode.exe" and only ships with the .NET Framework SDK version 1.0 and 1.1.

  2. Install the package to your system and locate one of the two tools (SignCode.exe or SignTool.exe).

Signing your Setups

Once the Authenticode file signing tool is installed on your system, you are ready to start signing your setup.

  1. Before publishing your final setup, select Publish > Settings from the menu and click on the Code Signing tab.

  2. Check the "Code sign setups" checkbox and fill in the available fields including selecting the desired tool's location on your system.

  3. Publish your final setup by selecting Publish > Build.

Tip: See the Code Signing Defaults section of the Preferences (Edit > Preferences, Code Signing page) for configuring defaults to use for code signing your setups every time you start a new project.

Testing your Signature

To verify that everything went according to plan and view your signature, SignTool.exe contains the verify command that determines whether the signing certificate was issued by a trusted authority, whether the signing certificate has been revoked, and, optionally, whether the signing certificate is valid for a specific policy. Simply run SignTool.exe and pass it the option verify followed by the full path to the setup file.

Alternatively, you could simply upload the setup to a web site and then download and run it from a computer using Windows XP SP2, or Windows Vista or later. You'll see the same information.

Getting More Information

There are many good resources on the Internet for finding out more about code signing, Authenticode, Windows XP/Vista or later, Security and related issues. Here are a few places to start.

  • MSDN: Introduction to Code Signing

  • Certify your Software Integrity with Thawte Code Signing Certificates

  • MSDN: Cryptography Tools (Windows)

  • MSDN: SignTool (Windows)

  • MSDN: File Signing Tool (Signcode.exe)

  • Microsoft: Signing and Checking Code with Authenticode

Copyright © 2015 Indigo Rose Software. All rights reserved.


Command Line Options

Overview

Setup Factory's design time and run time support various command line options that can be passed, thus providing developers and network administrators more control over the install, uninstall and build process.

Tip: The global variable _CommandLineArgs can be used to determine what arguments were passed to the installation executable.

The available command line options are grouped into the following three categories:

  • Install Command Line Options

  • Uninstall Command Line Options

  • Unattended Build Options

Install Command Line Options

The following command line options are supported by the Setup Factory installer:

/S:<<optional ini file>>

Allow an install to be run in silent mode. As a result, no screens or dialogs will be shown. If /S is passed on the command line it will set the global variable _SilentInstall to true if the Enable silent/unattended install option is selected in project settings.

This command line option also has an optional INI file that can be passed containing session variable values. For example:

"C:\output\setup.exe" "/S:C:\setupvars.ini"

This will cause the session variables in the INI file to be used for the setup. The INI file should be in the format:

[SetupValues]

%AppFolder%=C:\Program Files\Your Product 2
%UserName%=Joe Blow
%Whatever%=Who knows

/T:<<file path>>

Every setup executable requires some temporary space on the user's hard drive during the installation process. By default, Setup Factory uses the user's TEMP directory for extracting temporary files and other miscellaneous operations. You can force the setup executable to use an alternate directory by using the /T command line option.

The syntax for the /T option is:

/T:<<file path>>

Replace "<<file path>>" with the path to the folder you want the setup executable to use for its temporary files. (Be sure to put quotes around the entire argument if the path includes any spaces.) If the folder doesn't already exist on the user's system, it will be created automatically.

For example:

"C:\Downloads\setup.exe" "/T:C:\My Temp Dir"

(forces the installer to use "C:\My Temp Dir" for temporary files)

/NOINIT

This command line option hides the "initializing..." dialog that appears when extracting dependency or primer files at the beginning of the install.

/W

This command line option forces the Setup Factory launcher of a multi-segment install to wait for the setup executable to return before exiting. This is useful if you're running the installer from another process and you want that process to wait for Setup Factory to finish before proceeding.

Note: This only applies to muti-segment setups since Web (Single File) setups always wait for return.

Note: It is best not to use the /W option on very large multi-segment installs because errors may occur due to memory issues. If the /W command line option is not used, the setup return code will always be 0 since it is being returned after the launcher performs the initial extraction.

Uninstall Command Line Options

The following command line options are supported by the Setup Factory uninstall program:

/S:<<optional ini file>>

Allow an uninstall to be run in silent mode. As a result, no screens or dialogs will be shown. If /S is passed on the command line it will set the global variable _SilentInstall to true if the Allow silent uninstall option is selected in uninstall settings.

This command line option also has an optional INI file that can be passed containing session variable values. For example:

Note: The /U command line option also must be used when calling the uninstall program. See /U for details.

"C:\Program Files\MyProduct\uninstall.exe" "/U:C:\Program Files\MyProduct\Uninstall\MyProduct.xml" "/S:C:\setupvars.ini"

This will cause the session variables in the INI file to be used for the uninstall. The INI file should be in the format:

[UninstallValues]

%UserName%=Joe Blow
%Whatever%=Who knows

/U:<<uninstall config file>>

This command line option must be used when calling the uninstall program from the command line. The location and filenames of the uninstall executable and configuration file are defined in the Uninstall Settings. For example:

"C:\Program Files\MyProduct\uninstall.exe" "/U:C:\Program Files\MyProduct\Uninstall\uninstall.xml"

Unattended Build Options

The following command line options are supported by Setup Factory's design environment for an unattended build process:

Note: The unattended build returns 0 as a process return code if successful, or non-zero if not. You can use this return code to make your batch files respond to the success or failure of the Setup Factory build process.

Unattended Build Return Codes

The following unattended build errors may be returned. For a list of build errors, see Build Error Codes.

0

Build successful.

-3

Failed to find build configuration.

-4

Failed to open project file.

-5

Projects from previous versions of Setup Factory must be converted before use in the current version.

-6

Setup Factory Personal Edition must be registered before a build can be completed.

Note: This error only applies to the Personal Edition of Setup Factory.

Command Line Options

/BUILD

Tells Setup Factory to build the project file passed in on the cmd line or from a batch file. For example:
"C:\Program Files\Setup Factory 9\SUFDesign.exe" /BUILD "C:\TestProj.suf"

Tip: If you are running the build from a batch file, you can use "start /wait", for example:
start "" /wait "C:\Program Files\Setup Factory 9\SUFDesign.exe" /BUILD ...

/CONFIG:<<ConfigName>>

Specifies the build configuration to use in the build. If not specified, the first build configuration found in the project is used. For example:

"C:\Program Files\Setup Factory 9\SUFDesign.exe" /BUILD "C:\TestProj.suf" "/CONFIG:DebugConfig"

/LOG:<<log file path>>

Specifies a log file to output build status to. If the file exists, the output will be appended to it. If the file does not exist, it will be created. For example:

"C:\Program Files\Setup Factory 9\SUFDesign.exe" /BUILD "C:\TestProj.suf" "/LOG:C:\output\Log.txt"

/STDOUT

Makes the build status go to the standard output device.

For example, if Setup Factory's build is run from another product that captures the standard output:

"C:\Program Files\Setup Factory 9\SUFDesign.exe" /BUILD "C:\TestProj.suf" "/STDOUT"

Or, if you want to pipe the output to a new file:

"C:\Program Files\Setup Factory 9\SUFDesign.exe" /BUILD "C:\TestProj.suf" "/STDOUT" > "C:\build_output.txt"

Or, if you want to append the output to an existing file:

"C:\Program Files\Setup Factory 9\SUFDesign.exe" /BUILD "C:\TestProj.suf" "/STDOUT" >> "C:\appended_build_output.txt"

/CONST:<<ini file path>>

Lets you specify an INI file that contains design-time constants to override the ones in the project. You can define as many design-time constants as you want in the INI file, with each constant on a separate line beneath the [Constants] section. Each constant that is defined in the INI file must already be defined in the project file. For example:

[Constants]
#OUTPUTDIR#=C:\Output\Foobar 2015\Release
#SETUPNAME#=foobar2010setup.exe
#BUILD#=release

When you use the /CONST option along with /BUILD, the specified project file is loaded into Setup Factory, the constants described in the specified unattended-build INI file are set, and the setup executable is generated-all without any interaction.

For example:
"C:\Program Files\Setup Factory 9\SUFDesign.exe" /BUILD "C:\TestProj.suf" "/CONST:C:\MyProj\Config.ini"


Build Error Codes

Overview

The following error codes may be generated during the build process:

1000

"Build cancelled."

1010

"Invalid internal pointer."

1022

"Failed to load global include file: <<filename>>."

1023

"Could not locate constants file:<<filename>>."

1024

"Output folder does not exist and cannot be created."

1025

"Setup file name cannot be empty."
"Setup file name must be at least 5 characters."
"Setup file name must have the .exe file extension."

1026

"Could not find unattended build constants file: <<filename>>"

1027

"Could not read build constants file: <<filename>>."

2001

"Run before build program <<filename>> does not exist."

2002

"Run after build program <<filename>> does not exist."

2040

"There are no language files included in the project."

2050

"Primer file not found: <<filename>>."

2051

"File missing: <<filename>>."

2052

"File missing: <<filename>>."

2053

"Image file not found (screen: <<screen name>>) <<image name>>."

2054

"Background image was not found: <<image name>>."

2057

"Error saving converted image: <<image name>>."

2080

"There is no default language specified for the project."

2081

"Default language <<language name>> does not have a messages file specified."

2082

"Failed to read default messages file: <<message filename>>."

2090

"File copy failed (<<filename>>): <<source>> -> <<destination>>."

2091

"File compression failed."

3010

"Failed to open config file for writing: <<config filename>>."

3012

"Failed to open setup archive for writing: <<archive filename>>."

3013

"Failed to launcher file to archive header: <<launcher filename>>."

3014

"Could not add the data marker to the archive header."

3015

"Error adding file number token to archive header."

3016

"Error adding setup engine to archive header: <<setup engine filename>>."

3017

"Error adding config file to archive header: <<config filename>>."

3018

"Error adding image file to archive header: <<image filename>>."

3019

"Error adding primer file to archive header: <<primer filename>>."

3020

"Error adding file to archive: <<source filename>> (<<archive filename>>)."

3021

"Failed to determine size of archive."

3022

"Failed to determine size of files archive."

3023

"Failed writing setup size to archive prior to code signing (<<system_error_code>>)."

3026

"Error adding icon file to archive header: <<icon filename>>."

3030

"Invalid output folder: <<output folder path>>."

3031

"Failed to create output folder: <<output folder path>>."

3032

"Could not open archive file: <<archive filename>>."

3033

"Could not determine amount of free space on drive: <<drive letter>>."

3034

"Invalid output drive <<drive letter>>."

3035

"There is not enough free space on the non-removable drive: <<drive letter>> Required: <<size>> bytes - Available: <<size>> bytes."

3036

"An error has occurred creating the disk set: "

"Could not determine free disk space."

"Not enough free space on disk for your chosen segment size."

"Could not open temporary archive."

"Could not open output file."

"Memory allocation error."

"Error writing to disk - Bad disk?"

"Build abort by user request."

"General read/write error."

3037

"Could not open compressed file for reading: <<filename>>."

3038

"Could not seek in compressed file: <<filename>>."

3039

"Failed to read compressed file: <<filename>>."

3040

"Could not write to archive file: <<filename>>."

3050

"Error: Plugin <<plugin name>> is not licensed for re-distribution."

3051

"Error: Plugin <<plugin name>> is not available."

3052

"Error: <<plugin name>> plugin platform is not compatible with output platform."

3100

"Script Error: <<location>> Line <<line number>> "Error Detail: <<error message>> in <<line in code>>."

4100

"Failed to resource stamp setup runtime."

4101

"Failed to update setup resources - operation not supported on build operating system."

4200

"Error UPX executable not found."

4201

"Error UPX compression failed."

4300

"Code sign tool executable does not exist: <<file path>>."

4301

"Code signing certificate file does not exist: <<file path>>."

4302

"Code sign private key file does not exist: <<file path>>."

4303

"Code sign output file does not exist: <<file path>>."

4304

"Execute program error executing code signing tool."

7000

"Screen <<screen name>> uses top banner style but no image file specified."

7001

"Screen <<screen name>> uses side banner style but no image file specified."

7002

"Screen <<screen name>> uses banner style "none" but no image file specified."

7003

"Custom output file segment size smaller than space needed for primer file(s) and setup executable. Output file segment size has been increased to: <<size>>."

7004

"Memory allocation error. Scaling back dictionary size from: <<size>> to <<new size>>."

7005

"Failed writing setup size to archive prior to code signing (<<system_error_code>>) attempt <<attempt_number>> retrying."

7010

"Warning: Screen <<screen name>> uses a scrolling text control with the 'load from file' option enabled but the file does not exist: <<file path>>".

7100

"Warning: Runtime module file: <<file path>> already in file list - leaving existing file."

7200

"Writing manifest to executable only supported on Windows 2000 and greater. Manifest will not be updated."

Note: See Requested User Privilege Level for more information on install manifests.

7250

"Failed to write permissions manifest to setup."

Note: See Requested User Privilege Level for more information on install manifests.

7400

"Warning: Resource Stamping Skipped - operation not supported on build operating system."

7401

"Warning: Failed to resource stamp setup runtime. (<<error code>>) <<error message>>."

7500

"File Skipped - Folder reference source file already exists in file list: <<file path>>."

7600

"Warning: This setup has no operating systems selected on the Requirements tab of Project Settings."


Setup Return Codes

Overview

The following process return codes may be returned by a Setup Factory installation:

0

The installation completed successfully without any errors.

5

The installation was aborted by the user.

10

"Invalid archive filename."

12

"Invalid start mode: archive filename."

14

"Invalid module name."

16

"Invalid start mode: archive offset"

18

"Failed self extraction."

20

"Invalid uninstall command line option."

22

"Invalid uninstall control file: <<filename>>."

24

"Failed to find <<file description>> data file."

26

"Failed to load <<file description>> data file."

28

"Invalid silent install INI file: <<filename>>."

50

Unable to open the archive file.

51

Unable to allocate the memory buffer.

52

Could not find the data segment.

53

Could not find setup size.

54

Failed to read the setup engine for extraction.

55

Could not start the setup.

56

Could not determine a temp directory name.

57

There is not at least 2MB of free space on TEMP drive.

100

The installation was built with the evaluation version and has reached the end of its evaluation period.

101

The user's system did not satisfy the installation's system requirements.

103

The installation's archive integrity check failed. This means that the setup's archive has been corrupted in some way.

104

A plugin used in the setup failed to be initialized.

105

The silent install's configuration INI file could not be found.

110

One or more of the installation's screens could not be displayed.

120

There is not enough memory on the user's system to complete the installation's decompression process.

121

The application's folder could not be created on the user's system.

123

A decompression error occurred during the installation. Possible causes include: Not enough disk space or invalid paths or filenames.

125

An error occurred while skipping a file in the archive.

126

An error occurred while copying one of the files.

127

An error occurred while making an uninstall entry.

128

The user running the installation does not have the appropriate system permissions to modify one or more target folders.

129

The target drive does not exist.

130

There is currently not enough free disk space on the target drive.

131

The user running the installation does not have the appropriate system permissions to modify the Registry.

132

The installation has reached the expiration period defined in Project > Expiration.

133

The installation has reach the "number of uses" limit defined in Project > Expiration.

140

The uninstall files folder could not be created.

142

The uninstall's data file (*.dat) could not be created.

143

The uninstall's configuration file could not be created.

144

The uninstall's data could not be opened from the archive.

145

The uninstall's data could not be written to the user's system.

146

The uninstall's Registry key could not be created.

147

The uninstall's Registry value could not be set.

148

The uninstall's shortcut could not be created.

500

One or more files could not be removed by the uninstall program.


Windows Basics

Overview

In order to use Setup Factory to its full potential, you need to have a solid understanding of some basic (and a few not-so-basic) Windows concepts. This chapter is meant to serve as a quick overview of these Windows basics, to help you gauge your current level of knowledge, and to establish some of the terminology used in the Setup Factory documentation.

If you need further help on these subjects, please consult your Windows documentation.

Mouse Maneuvers

Files, Folders and Paths

Shortcuts

Shortcut Folders

File Associations

The Registry

Command Line Arguments

The Windows Clipboard

CRC Values


Mouse Maneuvers

Overview

There are eight basic maneuvers you should be able to perform with your mouse:

Click
Double-click
Right-click
Ctrl-click
Shift-click
Drag
Drag Select
Drag and Drop

Back to: Windows Basics


Click

Mouse Maneuvers

Overview Click

Clicking the mouse is as simple as it gets. Simply position the mouse pointer over the item that you want to "click" on, and then press and release the left mouse button once. The trick is to do this without moving the mouse.

(If you move the mouse while you click, Windows might think that you meant to perform a drag and drop instead.)

Tip: If you find it difficult to click on something without moving the mouse at the same time, try changing how you grasp the mouse with your hand. Some people like to rest their whole hand on the mouse; others prefer to cradle their hand over the mouse and move it with their thumb and ring finger. If you're right-handed, your index (first) finger should rest softly on the left mouse button, and your middle (second) finger should rest softly on the right mouse button. You don't want to let go of the mouse before you click, or the mouse might move, causing you to click on the wrong thing.

Next: Double-click


Double-click

Mouse Maneuvers

Overview Double-click

Double-clicking is a lot like clicking. You position the mouse pointer over the item that you want to "double-click" on, and then press and release the left mouse button twice, quickly, without moving the mouse.

You have to click twice quickly, or Windows will see your clicks as two normal clicks, instead of one double-click. And you mustn't move the mouse between clicks, or Windows will think you wanted to click two different things really fast.

Tip: Windows actually "detects" a double-click whenever you click twice in the same place within a certain amount of time. You can lengthen or shorten this time by adjusting the "double-click speed" in your Mouse settings, which you can access from the Windows Control Panel (usually by choosing Start > Settings > Control Panel).

Next: Right-click


Right-click

Mouse Maneuvers

Overview Right-click

A right click is just like a normal click, but instead of pressing the left mouse button, you press the right mouse button instead.

Right-clicking usually displays a pop-up menu with a list of menu items specific to whatever you right-clicked on. We often refer to this pop-up menu as a "right-click menu" or "right-click context menu."

Note: If you're right-handed, you should press the right mouse button with your middle finger (the second finger from the left). Using your index finger (the first finger on the left) for both left-clicking and right-clicking is not only slower, it may actually lead to muscle cramps or more serious medical conditions.

Next: Ctrl-click


Ctrl-click

Mouse Maneuvers

Overview Ctrl-click

Ctrl-clicking (pronounced "control clicking") is easy. To do it, you just press and hold the Ctrl key down while you click the mouse.

In Setup Factory (as in Windows), you can ctrl-click to add individual items to your current selection. For example, ctrl-clicking on a list item will select that item in addition to any items that are already selected.

Normally, when you click on five items in a row, you select each of the five items separately, one at a time. But if you ctrl-click on five items in a row, each item is added to your selection, so you end up having all five items selected at once. (Having more than one thing selected at once is known as "multiple selection.")

Tip: You can subtract individual items from your current selection by ctrl-clicking on items that are selected; ctrl-clicking on a selected item will deselect that item (i.e. it will remove that item from the current selection).

Next: Shift-click


Shift-click

Mouse Maneuvers

Overview Shift-click

Shift-clicking is easy. To do it, you just press and hold the Shift key down while you click the mouse.

In Setup Factory (as in Windows), you can shift-click to extend your current selection in a list box. In other words, shift-clicking lets you select a range of items, or "all of the items between point A and point B."

For example, if you click on a list item and then shift-click on another list item, you will automatically select all of the items between the first item you clicked and the item that you shift-clicked.

Next: Drag


Drag

Mouse Maneuvers

Overview Drag

Dragging is simply the act of "grabbing onto" an item with the mouse pointer and dragging it somewhere else.

To drag something, first position the mouse pointer over the item you want to drag. Then, "grab onto" the item by pressing (and holding) the left mouse button. Hold the left mouse button down while you "drag" the item by moving the mouse. When you've positioned the item where you want it, "let go" of it by releasing the mouse button.

Tip: You can abort a drag by pressing the Esc key.

Next: Drag Select


Drag Select

Mouse Maneuvers

Overview Drag Select

Drag selecting is a technique you can use to select multiple items at once. It basically involves drawing a temporary "box" around the items that you want to select by dragging the mouse pointer from one point to another.

To drag select a bunch of items, position the mouse pointer somewhere on the "surface" that the items are located on. (Don't position it on an item, or you'll just end up moving that item instead.) Press the left mouse button and hold it down while you move the mouse—the temporary drag-select box will appear to outline the selection area. "Stretch" the drag-select box by dragging the mouse until the selection area includes all of the items that you want to select, and let go of the mouse button. When you release the mouse button, any items within the drag-select box will be selected, and the drag-select box will disappear.

Next: Drag and Drop


Drag and Drop

Mouse Maneuvers

Overview Drag and Drop

Dragging and dropping simply means dragging an item from outside Setup Factory and "dropping" it into the design environment. You can use this technique to "drag" things like files into your project.

Tip: To drag an item between applications when their windows are maximized, select the item in the source application, drag it to the task bar at the bottom of your screen, and hold it over the tray button for the desired window. After a moment, that window will come to the front, and you can continue dragging the item to wherever you wanted it to go.

Next: Overview


Files, Folders and Paths

Overview

Working with Setup Factory is a lot easier if you have a solid understanding of files, folders, and the "paths" that are used to describe them. If you're new to Windows and hierarchical file systems, you should pay extra attention to this section.

Files
Extensions
Folders
Drives
Partitions
Root Folder
Paths

Back to: Windows Basics


Files

Files, Folders and Paths

Overview Files

Information on computers is stored in files. A file is simply a collection of data that a computer stores under a specific name, known as the filename. (In other words, a file is a bunch of data that the computer stores as one unit and that you can access by name.)

When you save a file, the data that makes up the file is written out to the hard drive, and whatever name you provided for the file is assigned to that collection of data on the hard drive.

When you load a file, you provide the name of the file that you want to load, and the corresponding data is read off the hard drive.

Warning: It's important to take special care when saving files. If you provide the name of a file that already exists, the new file will replace or "overwrite" the old file. Most applications will warn you before this happens, asking you to verify that you really want to overwrite the existing file. Be sure to heed the warning; once a file is overwritten, it can't be restored.

Files vary in size and can contain all sorts of data, from text, images and sounds, to database records and the "machine language" code that programs are made of.

Next: Extensions


Extensions

Files, Folders and Paths

Overview Extensions

An extension is the part of a filename that is used to indicate what kind or "type" of data is contained within a file.

A file extension consists of a period (.) followed by one or more characters at the end of a filename. Windows uses the file extension to determine what kind of information is contained in a file. For example, in the filename myfile.txt, .txt is the file extension that identifies myfile.txt as a text file.

Tip: When reading filenames out loud, the period in the extension is usually pronounced "dot." So myfile.txt would be pronounced "myfile dot text" or "myfile dot tee ex tee."

Next: Folders


Folders

Files, Folders and Paths

Overview Folders

Files are usually organized into groups using folders. Folders are essentially just containers for files. Like files, folders have names that you can use to access them. Each folder can contain any number of files, and even other folders (or "sub-folders").

Note: A "sub-folder" is just a folder that happens to be located in another folder. You can make any folder a sub-folder by placing it in another folder.

Windows uses a hierarchical file system. This means that storage space can be organized into multiple levels of folders and sub-folders, forming what is often referred to as a "directory tree." The base of the directory structure is known as the root folder, or just the "root" for short. Within this root folder there can be files and sub-folders, and within those sub-folders there can be other files and sub-folders as well.

Note: Every file on your computer is located in a folder, whether it's the root folder on one of your drives, or some other folder located inside the root folder. (Or a folder inside a folder that is inside the root folder, or a folder inside a folder that is inside a folder that is...well, you get the idea.)

This hierarchy of folders is why every file has a path. A path is a string of text that describes where a file is stored. It's basically just a list of the different folders that you would need to open in order to reach the file.

Each folder acts like a container for all the files and folders that are "in" it. The files and sub-folders in a folder can be copied, moved or deleted all at once by copying, moving or deleting the folder that contains them.

Much like hanging folders in a filing cabinet, folders make it easier to organize and locate your files. If the files on a computer were all kept in one place, it would be very difficult to find a particular file. Folders allow related files to be grouped together so it's easier to find them.

Note: Folders are also often called directories. In Windows, the terms "folder" and "directory" both refer to the same thing.

Next: Drives


Drives

Files, Folders and Paths

Overview Drives

A drive is a form of fixed, networked or removable media used as a storage device.

The term "drive" can also refer to the drive letter, which is the letter assigned to the drive during the computer boot process. A single letter of the alphabet is assigned to each drive as it is detected at startup. The letters "A" and "B" are reserved for floppy drives, and the rest of the letters (from C to Z) are assigned in order to the various hard drives, CD-ROM drives, and any other drives attached to the system.

For example, if your system has a single hard drive and a CD-ROM drive, your C: drive is your hard drive, and your D: drive is your CD-ROM. If your hard drive is split into two logical drives or "partitions," then C: and D: would refer to those partitions, and your CD-ROM drive would be E:.

Next: Partitions


Partitions

Files, Folders and Paths

Overview Partitions

A partition is a logical division of a hard drive into smaller parts, where each part is seen as a separate "drive" by the operating system. For example, a single 30 GB hard drive could be separated into three 10 GB partitions, which would appear to the operating system as three drives (C:, D: and E:).

Next: Root Folder


Root Folder

Files, Folders and Paths

Overview Root Folder

The root folder (or "root" for short) is the "base" or "main" folder on any drive. The root folder is where all of the other folders on a drive are located. When you double-click on the C: drive in My Computer, you're opening the root folder of the C: drive. All the folders on the C: drive are located in the "root" of C:.

The root folder is always named "\" in Windows. For example, the path to the root of the D: drive is:

D:\

Next: Paths


Paths

Files, Folders and Paths

Overview Paths

A path is a string of text that describes where a file or folder is stored in a hierarchical directory structure. There are three kinds of paths you can use in Setup Factory: full paths, relative paths and UNC paths.

Full Paths

Full or "absolute" paths provide "complete" directions to locate a file, starting right from the drive letter that the file is located on. A full path begins with the drive letter and includes the name of each folder that would need to be opened, in turn, in order to access the desired folder or file. The folder names are separated by backslash characters (\). Full paths have the following general format:

drive letter>:\<folder name>\<folder name>\<filename>

For example:

  • The path to the root folder on the C: drive is:
    C:\

  • The path where Setup Factory 9 is installed by default is:
    C:\Program Files\Setup Factory 9

  • The path to Notepad.exe on your system is probably something like:
    C:\Windows\Notepad.exe

Relative Paths

Relative paths provide "partial" directions to locate a file starting from a given folder (often the current working directory). Relative paths look just like full paths, but they're missing the drive name and possibly some folder names too. The simplest relative paths consist of a single folder or filename. Relative paths have the following general format:

<folder name>\<folder name>\<filename>

For example:

  • The relative path to a Data folder in the current working directory would be:
    Data

  • The relative path to the Setup Factory 9 application from the Program Files folder would be:
    Setup Factory 9\SUFDesign.exe

  • The relative path to a readme file in a sub-folder named Docs would be:
    Docs\readme.txt

  • The relative path to the root folder on the same drive is always:
    \

Dots and dot-dots

There are two special folder names that you can use in relative paths:

One dot (.) always refers to the current folder.
Two dots (..) refers to the folder that is one level higher than the current folder.

For example:

  • The relative path to a program named foo.exe in a folder two levels above the current folder is:
    ..\..\foo.exe

  • The relative path to a folder named Images in a folder three levels above the current folder is:
    ..\..\..\Images

  • The relative path to a file named whatsup.doc in the current folder can either be written as:
    whatsup.doc

    or as:
    .\whatsup.doc

UNC Paths

The Universal Naming Convention (UNC) is a standard method of describing the location of files and other resources shared over a network. In Windows, UNC paths begin with two backslashes (\\), followed by the server name, which is the name assigned to the computer where the shared resources are located. The server name is followed by another backslash (\) and the share name, which is simply the name that was given to the volume or storage device when it was shared. This is then followed by the path to the desired file or folder on that shared volume.

UNC paths have the following general format:

\\<server name>\<share name>\<folder name>\<filename>

For example:

  • The UNC path to the Setup Factory 9 folder on a C: drive which is shared as "D2" on a computer named "R2" would be:
    \\R2\D2\Program Files\Setup Factory 9

  • The UNC path to a file named foo.txt in the temp folder of a drive which is shared as "MAIN" on a computer named "DOROTHY" would be:
    \\DOROTHY\MAIN\temp\foo.txt

Next: Overview


Shortcuts

Windows Basics

Overview Shortcuts

A shortcut is a very small file in the Windows operating system that points or "links" to a web site or another file.

Here's what a shortcut to notepad.exe looks like:

Notice the little curly arrow on the icon that tells you this is a shortcut.

Each shortcut file contains information about where the file or web site that it "points" to is located. When a user double-clicks on a shortcut file, the file or web site that it points to is opened instead.

Shortcut files have a .lnk, .url or .pif extension that is hidden by the Windows operating system:

.lnk - shortcuts to files and folders
.url - shortcuts to web sites
.pif - shortcuts to DOS batch files

It's easy to forget that shortcuts are files. Normally the only indication you have that an item is a shortcut is the little curly arrow on its icon, or the fact that it's located in the Start menu or on the Quick Launch desktop toolbar. The fact that shortcuts are actually regular files is very well hidden by Windows.

In fact, the items in your Favorites menu and the "programs" in your Start menu are all shortcuts. Adding a shortcut to the Start menu is nothing more than copying a shortcut file into the designated "Start menu" folder on the user's system.

Next: Shortcut Folders


Shortcut Folders

Windows Basics

Overview Shortcut Folders

Shortcuts are often organized into folders, known as shortcut folders. A shortcut folder is simply a folder that contains shortcut files.

A good example of shortcut folders are the "program groups" that keep your Start -> Programs menu organized. For instance, by default all Indigo Rose product-specific shortcut folders are installed in a shortcut folder named "Indigo Rose Corporation" inside the "Programs" shortcut folder.

Next: File Associations


File Associations

Windows Basics

Overview File Associations

File associations tell Windows what actions can be performed on different types of files, what programs should be used to carry out each of those actions, and the paths to where those programs can be found.

Each file association associates a specific file extension with a command to use a program to do something to that file. For example, a file association can tell Windows that when files ending with .doc are double-clicked, they should be opened with Microsoft Word.

The program that is associated with a file extension is known as the default viewer for that type of file. For instance, Notepad is the default viewer for .txt files when Windows is installed.

File associations are stored in the Registry under HKEY_CLASSES_ROOT.

Next: The Registry


The Registry

Windows Basics

Overview The Registry

The Registry is a central database provided by the Windows operating system where system and software configuration details are stored. It's arranged into a hierarchical structure that is similar to the way folders and files are organized on a hard drive.

The Registry is organized into six main folders, called main keys. Each of these main keys can contain any number of sub-folders, called sub keys. Information in the Registry is stored inside the main keys and sub keys as values.

There are three different types of values that can be stored in the Registry: String, Binary, and DWORD. String values contain strings of characters, Binary values contain binary data, and each DWORD value contains a single 32-bit ("double word") value.

Each main key in the Registry contains a different kind of information.

The six main keys are:

HKEY_CLASSES_ROOT

HKEY_CLASSES_ROOT is used to store information on different aspects of shell integration, like file associations, OLE, DDE, and drag-and-drop operations.

This key is actually a link to HKEY_LOCAL_MACHINE\SOFTWARE\Classes. Storing information in HKEY_CLASSES_ROOT is the same as storing information in HKEY_LOCAL_MACHINE\SOFTWARE\Classes, and vice-versa.

HKEY_CURRENT_USER

Like HKEY_CLASSES_ROOT, this is actually a link to another key. In this case, it points to the key in HKEY_USERS that belongs to the user who is currently logged onto the system. This is where configuration information for the current user is stored.

HKEY_LOCAL_MACHINE

HKEY_LOCAL_MACHINE contains information about system hardware, peripherals, installed software, OLE and software configuration, and other Windows configuration details.

HKEY_USERS

This is where user-specific configuration information is stored. Individual sub keys hold settings for each user, and the default settings are kept in a sub key named .Default.

HKEY_CURRENT_CONFIG

HKEY_CURRENT_CONFIG stores information for plug-and-play devices and the various hardware configurations that have been defined.

HKEY_DYN_DATA

HKEY_DYN_DATA is used by Windows to store dynamic information that changes frequently during the normal operation of Windows. It's usually best to leave this key alone.

Tip: In Setup Factory, you can use the Registry actions to read from and write to the Registry.

Next: Command Line Arguments


Command Line Arguments

Windows Basics

Overview Command Line Arguments

Command line arguments are just values that are passed to an executable file when it is run. Also known as "command line switches" or "command line options," command line arguments are usually used to set program options, or to pass along the location of a file that the program should load.

They're called command line arguments because they are generally used when launching a program from a command line (also known as the "DOS prompt" in Windows). In fact, command line arguments go way back, to the days before computers had fancy graphical user interfaces, when typing stuff into a command line was the only way to run a program.

When a program is running, it can access any command line arguments that were passed to it and make decisions about them. Every executable accepts different arguments and interprets them in different ways.

For example, entering C:\abc.exe /W /F on a command line would run a program called abc.exe and pass two command line arguments to it: /W and /F. The abc.exe program would see those arguments and handle them internally.

Note: Not all executables use command line arguments, and the list of meaningful command line arguments is specific to each program. /W might mean "wait for return" in one program, but it could mean "enable wacky walk animation" in another—or it might not even be recognized at all.

Tip: Many programs will display a list of the command line arguments they support if you run them with the /? option.

You can test command line arguments by running an executable from the "Command Prompt" in Windows or from the "DOS prompt" in older versions of Windows. You can also use command line arguments in program shortcuts, or when running an application by using Start -> Run.

For example, to run notepad on a typical Windows XP system, you can go to Start > Run and type in:

C:\Windows\notepad.exe

This will start notepad with a blank document. In this case, there are no command line arguments being passed to the program (notepad).

But, if you go to Start > Run and also type in the path to an existing text file:

C:\Windows\notepad.exe C:\Docs\Info.txt

...then notepad will open up with that C:\Docs\Info.txt document loaded into it. In this case, "C:\Docs\Info.txt" is a command line argument being passed to notepad.exe. Notepad detects the argument, sees that it's the path to a text file, and loads that file automatically (which is what notepad does when you pass it the path to an existing text file).

Tip: Note that command line arguments are separated by spaces. If you need to pass a command line argument that contains one or more spaces, you can surround the argument with quotes. The quotes will make the spaces part of the argument. For example:

abc.exe D:\open this file.txt

...would be seen as 3 arguments: "D:\open", "this" and "file.txt". To pass the path as a single argument, you need to surround it with quotes, like this:

abc.exe "D:\open this file.txt"

Next: The Windows Clipboard


The Windows Clipboard

Windows Basics

Overview The Windows Clipboard

The Windows clipboard is a storage area for items the have been cut or copied. Whenever you cut or copy something, it is automatically placed in the clipboard for you. You can then "paste" a copy of the item from the clipboard to anywhere you want.

Note: If you've ever cut, copied or pasted anything in a Windows application, you've already used the Windows clipboard.

Technically, the clipboard is just a bit of physical memory (i.e. RAM) that has been set aside to hold any stuff that you might happen to copy or cut. It can only hold one item at a time, so when you cut or copy something, it replaces anything that is already in the clipboard.

You can keep pasting the contents of the clipboard as often as you like. Anything you put in the clipboard will remain there until you overwrite the contents by cutting or copying something else into the clipboard. (Or until you empty the clipboard by rebooting Windows.)

Note: You can cut, copy and paste items from one place to another in the same application, or even to a different application altogether.

There are three clipboard functions that can be performed in virtually all Windows applications: cut, copy and paste.

Cut

When you cut something, it is removed from its current location, and placed in the Windows clipboard.

Tip: The easiest way to cut something is by selecting it and pressing Ctrl+X on your keyboard. You can also right-click on it and select Cut from the context menu.

Copy

When you copy something, it remains in its current location, and a duplicate of it is placed in the Windows clipboard.

Tip: The easiest way to copy something is by selecting it and pressing Ctrl+C on your keyboard. You can also right-click on it and select Copy from the context menu.

Paste

When you paste something, it is copied "back" from the Windows clipboard to the location you have selected. (This assumes that the location you're pasting to is able to hold whatever is on the clipboard; you can't paste an MPEG video into a text editor, for instance, because the text editor is made to hold text, and not video files.)

If you have something selected at the destination when you paste, the clipboard contents will replace that stuff, so be careful not to overwrite things by mistake. For example, if you have a bunch of text selected and you paste the word "bamboozled" in from the clipboard, the text you had selected will be replaced by the word "bamboozled."

You can keep pasting copies of the clipboard contents as long as you want. In fact, pasting is a great way to make multiple copies of something. Just cut or copy an item into the clipboard, and then paste it back as many times as you want.

Tip: The easiest way to paste is by pressing Ctrl+V on your keyboard. You can also right-click and select Paste from the context menu.

Next: CRC Values


CRC Values

Windows Basics

Overview CRC Values

CRC values are calculated using an algorithm known as the Cyclic Redundancy Check, or "CRC" for short. Basically, this involves generating a 32-bit number (or "CRC value") based on the contents of a file. If the contents of a file change, its CRC value changes as well. This allows the CRC number to be used as a "checksum" in order to identify whether or not the file has changed. It also allows you to distinguish between different versions of a file by comparing its CRC value to the CRC values of the originals.

The basic idea of the CRC algorithm is to treat all the bits in a file as one big binary number, and then divide that number by a standard value. The remainder from the division is the CRC value.

You can think of this value as being like a fingerprint for each file. Unlike human fingerprints, however, it isn't impossible for two files to have the same CRC-32 value. Setup Factory uses an industry-standard CRC-32 algorithm which generates CRC values that are 32 bits in length. This means that one in every 4,294,967,296 files could have the same CRC "fingerprint."

A file doesn't have to change much for its CRC value to be different. In fact, if even just one bit in a file changes, the CRC value for that file will change as well. If all you did was change one letter in a readme.txt file between version 1 and version 2, the CRC value for that readme.txt file would be completely different.

CRC values can be calculated for any type of file.

Although the chances of any two files having the same CRC value are incredibly small, the CRC value alone isn't enough to guarantee an accurate identification. If you need to be absolutely sure, check the CRC in addition to other information about the file, such as the size of the file in bytes and its location on the user's system.

Next: Overview


Copyright Information

Copyright Info

Proprietary Notice

The software described in this document is a proprietary product of Indigo Rose Software Design Corporation and is furnished to the user under a license for use as specified in the license agreement. The software may be used or copied only in accordance with the terms of the agreement.

Information in this document is subject to change without notice and does not represent a commitment on the part of Indigo Rose Software Design Corporation. No part of this document may be reproduced, transmitted, transcribed, stored in any retrieval system, or translated into any language without the express written permission of Indigo Rose Software Design Corporation.

Trademarks

Setup Factory and the Indigo Rose logo are trademarks of Indigo Rose Software Design Corporation. All other trademarks and registered trademarks mentioned in this document are the property of their respective owners.

Copyright

Copyright © 2015 Indigo Rose Software Design Corporation.
All Rights Reserved.

LUA is copyright © 2015 Tecgraf, PUC-Rio.

UPX executable compression (http://upx.sf.net) copyright © 1996-2015 Markus Franz Xaver Johannes Oberhumer, copyright © 1996-2015 Laszlo Molnar, copyright © 2000-2015 John F. Reiser. All Rights Reserved.


Ordering Information

Ordering Information

Benefits of Ordering

When you order Setup Factory you will receive:

  • Setup Factory program with the latest revisions and enhancements.

  • A license to distribute, royalty-free, the installations that you create with Setup Factory.

  • A professionally written electronic User's Guide and Program Reference.

Please visit http://www.indigorose.com for available support resources and policies.

Pricing

Current pricing information can be obtained from our web site at www.indigorose.com.

Setup Factory is licensed on a royalty-free, per developer basis. Multiple license discounts and site licenses are available. Purchase orders from qualified government, corporate, and educational institutions are terms Net 30 and subject to approval. Please contact our sales department for details.

Contact Information:

Our friendly sales staff is ready to answer any questions you may have. Please visit http://www.indigorose.com for full contact details.


System Requirements

Overview

Design Environment

The recommended system requirements for the Setup Factory design environment are:

Windows XP SP2, Windows Vista, Windows 7, Windows 8, Windows 8.1, Windows 10 or greater
Pentium 4 or equivalent
500 MB RAM or greater
100+ MB free hard drive space
Resolution: 1040x768

Run-time Application (Built Installer)

The minimum system requirements for the Setup Factory installer are:

Minimum

Windows XP SP2 or greater.
Pentium 233-megahertz (MHz) processor
64 MB RAM
800x600 SVGA display
Video card set to 8 bit 256 color or greater (recommended)
20+ MB free hard drive space

Note: The following HTTP actions require Internet Explorer 4.0 or greater: HTTP.GetConnectionState, HTTP.DownloadSecure and HTTP.SubmitSecure.


Converting Actions

Importing Setup Factory 6.0 Projects

Overview What Is Converted What Is Not Converted (Gotcha's) Converting Actions

Below is a categorical list of Setup Factory 6.0's actions and their equivalent Setup Factory 9 script:

Note: One significant difference between Setup Factory 6.0 and Setup Factory 9 is the use of variables. Setup Factory contains two different types of variables, Session Variables and Lua variables. Lua variables are used in action script whereas session variables are used either for display purposes on screens, or in file path situations. While you can use session variables in action script using the SessionVar actions, the type of variable used will depend upon its intended use. Keep this in mind when reading the equivalent action examples.

Another thing to watch out for is escaping special characters in strings. For example, you must escape all backslashes in strings. If you have a path string such as C:\Folder\File.txt, it would become "C:\\Folder\\File.txt".

  • Control Structures

  • Dialogs

  • File Information

  • File Operations

  • Folders

  • INI Files

  • Internet

  • Open/Close Programs

  • Reboot

  • Registry

  • Services

  • Shortcuts

  • Strings

  • Text Files

  • Variables

Control Structures

Abort Setup

Application.Exit();

Blank Line

There is no action in Setup Factory 9. You can simply add a carriage return while you are in the action editor.

Comment

Comments are denoted with "--" characters in action script. For example:

-- This is my comment.

You can also have multi line comments using --[[ to start, and ending with ]]. For example:

--[[ This is the start of my comments.
this line is still commented
this line is still commented
]]

END IF

Since control structures are now part of the Lua scripting language, this is not an action in Setup Factory 9. However Setup Factory 9 does still contain this control structure terminator as seen below:

end

END WHILE

Since control structures are now part of the Lua scripting language, this is not an action in Setup Factory 9. However Setup Factory 9 does still contain this control structure terminator as seen below:

end

GOTO Label

Setup Factory 9 does not contain an equivalent structure for a GOTO statement. However some features that may be used for that type of design are functions. You can also break out of loops using the break; statement.

IF Statement

If statements are no longer actions in Setup Factory 9. They are now part of Setup Factory's scripting language, Lua. For more information about "if statements", read this Scripting Guide topic. Below is a simple example of an if statement.

-- Here is a simple example of an if statement:
if (strMyString == "Hey") then
-- Insert code here.
end

LABEL

Since Setup Factory 9 does not contain an equivalent of a GOTO statement, it does not contain an equivalent of a label.

WHILE

While loops are no longer actions in Setup Factory 9. They are now part of Setup Factory's scripting language, Lua. For more information about while loops, read this Scripting Guide topic. Below is a simple example of a while loop.

-- Here is a simple example of a while loop:
a = 1;
while a < 10 do
a = a + 1;
end

Dialogs

Show Message Box (Your Message Here)

result = Dialog.Message("Notice", "Your Message Here", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);

Show Yes/No Dialog (%YesNoResult% = Your Question Here?)

There is really no reason to use session variables for this action since it returns a numerical value representing the button.

result = Dialog.Message("Notice", "Your Question Here?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- To check the result, you would use something like the following:
if (result == IDYES) then
-- The user clicked the Yes button. Insert code here.
else
-- The user clicked the No button. Insert code here.
end

File Information

Read File Information (%FileInfoVar% = Version of %SrcDir%\YourFile.ext)

Note: To compare file versions in Setup Factory 9, you would use the String.CompareFileVersions action.

-- Return a table of information about the file.
tbFileInfo = File.GetVersionInfo(_SourceFolder.."\\YourFile.ext");

-- Access the file's "File version" from the table.
strFileVer = tbFileInfo.FileVersion;

Or to use and store the result in a session variable:

-- Return a table of information about the file.
tbFileInfo = File.GetVersionInfo(SessionVar.Expand("%SourceFolder%\\YourFile.ext"));

-- Access the file's "File version" from the table and store it in a string variable.
strFileVer = tbFileInfo.FileVersion;

-- To create a session variable to store the file version, you would use:
SessionVar.Set("%FileInfoVar%", strFileVer);

Read File Information (%FileInfoVar% = CRC value of %SrcDir%\YourFile.ext)

-- This stores the CRC value in a variable whose type is a number.
FileInfoVar = File.GetCRC(_SourceFolder.."\\YourFile.ext");

Or to use and store the result in a session variable:

FileInfoVar = File.GetCRC(SessionVar.Expand("%SourceFolder%\\YourFile.ext"));

-- To create a session variable to store the CRC value, you would use:
SessionVar.Set("%FileInfoVar%", FileInfoVar);

Read File Information (%FileInfoVar% = Size of %SrcDir%\YourFile.ext)

-- This stores the value in bytes in a variable whose type is a number.
FileInfoVar = File.GetSize(_SourceFolder.."\\YourFile.ext");

Or to use and store the result in a session variable:

FileInfoVar = File.GetSize(SessionVar.Expand("%SourceFolder%\\YourFile.ext"));

-- To create a session variable to store the file size, you would use:
SessionVar.Set("%FileInfoVar%", FileInfoVar);

Read File Information (%FileInfoVar% = Existence of %SrcDir%\YourFile.ext)

bFileInfoVar = File.DoesExist(_SourceFolder.."\\YourFile.ext");

-- The variable returned is a boolean variable.
-- So to check the variable you would use:
if (bFileInfoVar) then
-- The file exists, so insert your code here.
else
-- The file does not exist. Insert your code here.
end

There is no reason to store the boolean result in a session variable. However to use session variables in the path:

bFileInfoVar = File.DoesExist(SessionVar.Expand("%SourceFolder%\\YourFile.ext"));

Read File Information (%FileInfoVar% = Short file name of %SrcDir%\YourFile.ext)

-- This stores the short file name path in the variable as a string.
FileInfoVar = File.GetShortName(_SourceFolder.."\\YourFile.ext");

Or to use and store the result in a session variable:

FileInfoVar = File.GetShortName(SessionVar.Expand("%SourceFolder%\\YourFile.ext"));

-- To create a session variable to store the short file name, you would use:
SessionVar.Set("%FileInfoVar%", FileInfoVar);

Read File Association (%FileLocation% = File associated with ".ext" extension)

FileLocation = File.GetDefaultViewer(".ext");

Or to store the result in a session variable:

-- Get the full path of the default viewer and store it in a session variable.
FileLocation = File.GetDefaultViewer(".ext");

-- Create a new session variable to store the default file viewer path.
SessionVar.Set("%FileLocation%", FileLocation);

Search for file (%FileSearchResult% = location of MyFile.ext)

Setup Factory 9's equivalent action requires you to specify what drive/folder you would like to search in, similar to the Search specific directories/drives option in Setup Factory 6.0. To search other drives, you can first determine all mapped drives using the Drive.Enumerate action and run additional File.Find actions on those as needed. Searching an entire machine is never a good idea without narrowing down the scope of the search in some way.

-- Returns a table containing the paths to all of the files that were found.
tbFileSearchResult = File.Find("C:\\MyDir\\", "MyFile.ext", false, false, nil, nil);

-- To access the first file that was found, you can reference the string in tbFileSearchResult[1].
-- If no files were found, tbFileSearchResult will equal nil. (tbFileSearchResult == nil)

Or to create a session variable to store the result, you would add the following to the previous example:

-- Create a new session variable to store the first file found.
SessionVar.Set("%FileSearchResult%", tbFileSearchResult[1]);

File Operations

Copy Files (C:\Dir 1\Old File.ext - > C:\Dir 2)

File.Copy("C:\\Dir 1\\Old File.ext", "C:\\Dir 2\\", true, true, false, true, nil);

Delete Files (C:\Dir 1\Old File.ext)

File.Delete("C:\\Dir 1\\Old File.ext", false, false, false, nil);

Install File (%TempDir%\MyFile.dat -> %AppDir%)

result = File.Install(_TempFolder.."\\MyFile.dat", SessionVar.Expand("%AppFolder%\\MyFile.dat"), FILE_INSTALL_SAMEOLDER, false, false);

Move Files (C:\Dir 1\Old File.ext - > C:\Dir 2)

File.Move("C:\\Dir 1\\Old File.ext", "C:\\Dir 2\\", true, true, false, false, nil);

Register File (%SysDir%\MyControl.dll)

Tip: There is now the action System.UnregisterActiveX used to unregister a file.

System.RegisterActiveX(_SystemFolder.."\\MyControl.dll");

Or using the system folder session variable:

System.RegisterActiveX(SessionVar.Expand("%SystemFolder%\\MyControl.dll"));

Register Font (%FontDir%\Myfont.ttf -> My Font)

Tip: There is also an action to unregister a font called System.UnregisterFont.

-- This example uses the Shell.GetFolder action to get the fonts folder.
System.RegisterFont(Shell.GetFolder(SHF_FONTS).."\\MyFont.ttf", "My Font", true);

Or using the Fonts folder session variable:

-- This example uses %FontsFolder% session variable expanded using SessionVar.Expand.
System.RegisterFont(SessionVar.Expand("%FontsFolder%\\MyFont.ttf"), "My Font", true);

Rename File (C:\YourDir\Old File.ext -> C:\YourDir\New File.ext)

File.Rename("C:\\YourDir\\Old File.ext", "C:\\YourDir\\New File.ext");

Set File Attributes (%AppDir%\MyFile.dat -> Read Only Archive)

File.SetAttributes(SessionVar.Expand("%AppFolder%\\MyFile.dat"), {ReadOnly=true, Archived=true});

Unzip Files (%SrcDir%\Patches\patch.zip -> %SrcDir%)

All of the ZIP actions in Setup Factory 9 are available as action plugins. By default, these will not be available in the action list in order to reduce the size of the runtime. To include these available actions in your project, select Resources > Plugins from the program menu and add the Zip action plugin. The actions will then become available through the action wizard and intellisense. See the action plugin's documentation for further examples.

Zip.Extract(_SourceFolder.."\\Patches\\patch.zip", {"*.*"}, _SourceFolder, true, true, "", ZIP_OVERWRITE_NEVER, nil);

Or using session variables in the path:

Zip.Extract(SessionVar.Expand("%SourceFolder%\\Patches\\patch.zip"), {"*.*"}, SessionVar.Expand("%SourceFolder%"), true, true, "", ZIP_OVERWRITE_NEVER, nil);

Folders

Create Directory (C:\YourDir)

Folder.Create("C:\\YourDir");

Remove Directory (C:\YourDir)

Folder.Delete("C:\\YourDir");

INI Files

Modify INI File (Set Value: %SrcDir%\Settings.ini [SectionName]:My Value = Value Data)

INIFile.SetValue(_SourceFolder.."\\Settings.ini", "SectionName", "My Value", "Value Data");

Or using the source folder session variable:

INIFile.SetValue(SessionVar.Expand("%SourceFolder%\\Settings.ini"), "SectionName", "My Value", "Value Data");

Modify INI File (Delete Value: %SrcDir%\Settings.ini [SectionName]:My Value)

INIFile.DeleteValue(_SourceFolder.."\\Settings.ini", "SectionName", "My Value");

Modify INI File (Delete Section: %SrcDir%\Settings.ini [SectionName])

INIFile.DeleteSection(_SourceFolder.."\\Settings.ini", "SectionName");

Read from INI File (%INIVar% = "%SrcDir%\Settings.ini":[Info], My Value)

-- Get the INI value and store it in the INIVar Lua variable.
INIVar = INIFile.GetValue(_SourceFolder.."\\Settings.ini", "Info", "My Value");

Or using and storing the result in a session variable:

-- Get the INI value and store it in the INIVar Lua variable.
INIVar = INIFile.GetValue(SessionVar.Expand("%SourceFolder%\\Settings.ini"), "Info", "My Value");

-- Create a session variable called %INIVar% and set its value to the value of INIVar.
SessionVar.Set("%INIVar%, INIVar);

Internet

Check Internet Connection (%IsConnected%)

Session variables are not useful in this action since the result is a boolean value, unless the website is stored within one.

-- Returns a boolean result of either true or false.
bIsConnected = HTTP.TestConnection("http://www.mydomain.com/myscript.php", 20, 80, nil, nil);

-- You can check the value using the following method:
if (bIsConnected) then
-- The user is connected. Insert code here.
else
-- The user is not connected. Insert code here.
end

HTTP Download (http://www.yoursite.com/yourdir/patch.exe -> %SrcDir%\Patches)

Tip: There is now an action available for secure downloads as well called HTTP.DownloadSecure

HTTP.Download("http://www.yoursite.com/yourdir/patch.exe", _SourceFolder.."\\Patches\\patch.exe", MODE_BINARY, 20, 80, nil, nil, nil);

Or using the source folder session variable:

HTTP.Download("http://www.yoursite.com/yourdir/patch.exe", SessionVar.Expand("%SourceFolder%\\Patches\\patch.exe"), MODE_BINARY, 20, 80, nil, nil, nil);

Submit to Web (POST: http://www.your-site.com/submit.php)

Tip: There is now an action available for secure submissions as well called HTTP.SubmitSecure.

-- The values returned are found in the variable "result".
result = HTTP.Submit("http://www.your-site.com/submit.php", myvalues, SUBMITWEB_POST, 20, 80, nil, nil);

Open/Close Programs

Call DLL Function (%DLLResult% = C:\MyDLL.dll:MyFunction("String 1","String 2",1,0))

-- Notice the escaping of the quotes inside of the string of the third parameter.
DLLResult = DLL.CallFunction("C:\\MyDLL.dll", "MyFunction", "\"String 1\",\"String 2\",1,0", DLL_RETURN_TYPE_LONG, DLL_CALL_CDECL);

-- If you want the result to be a session variable you would add the following:
SessionVar.Set("%DLLResult%, DLLResult);

Close Program (Program "notepad.exe", Send close message)

The close program action in version 6.0 did a few steps behind the scenes. The same is possible in version 9, however requires you to first find the window handle of the window or process, and then close it.

There are a couple methods to close a window:

-- Close the window using its window handle by sending it a close message.
Window.Close(TargetWindowHandle, CLOSEWND_SENDMESSAGE);

-- Close the window using its window handle by terminating its process.
Window.Close(TargetWindowHandle, CLOSEWND_TERMINATE);

To close a window you need to get the window handle to the program. There are a couple methods to get this information: You can either search by window title or by the path to the executable that spawned the process:

-- Get all of the processes running.
tbProcesses = Window.EnumerateProcesses(false);

tbWindowTitles = Window.EnumerateTitles(true);

Here is an example that closes all instances of a program by searching for the filename:

-- The filename to check for.
strFileToCheck = "notepad.exe";

-- Get all of the running processes.
tbProcesses = Window.EnumerateProcesses(false);

-- Search through the processes and check the file path who spawned the process.
for j, file_path in pairs(tbProcesses) do

-- Split the path into its components to get its filename.
tbPathPart = String.SplitPath(file_path);
-- Generate the complete filename.
strFilename = tbPathPart.Filename..tbPathPart.Extension;

if (String.CompareNoCase(strFilename, strFileToCheck)== 0) then
-- Close the window by sending it a close message.
Window.Close(j, CLOSEWND_SENDMESSAGE);
-- To terminate the process you could use:
-- Window.Close(j, CLOSEWND_TERMINATE);
end
end

Execute (%SrcDir%\Patches\patch.exe)

Another action that is very similar is the Shell.Execute action with an "execute" verb.

result = File.Run(_SourceFolder.."\\Patches\\patch.exe", "", "", SW_SHOWNORMAL, false);

Or using the source folder session variable:

result = File.Run(SessionVar.Expand("%SourceFolder%\\Patches\\patch.exe"), "", "", SW_SHOWNORMAL, false);

Open Document(open C:\MyText.txt)

File.Open("C:\\MyText.txt", "", SW_SHOWNORMAL);

Or if you need to use different verbs beyond "open", you could use the following action:

Shell.Execute("C:\\MyText.txt", "open", "", "", SW_SHOWNORMAL);

Reboot

Delete File on Reboot (C:\Dir 1\File1.ext)

File.DeleteOnReboot("C:\\Dir 1\\File1.ext");

Move File on Reboot (C:\Dir 1\File1.ext -> C:\Dir 2\File1.ext)

File.MoveOnReboot("C:\\Dir 1\\File1.ext", "C:\\Dir 2\\File1.ext");

Run File on Reboot (C:\Dir 1\File1.exe)

File.RunOnReboot("C:\\Dir 1\\File1.exe", "");

Registry

Modify Registry (Create Key: HKEY_CURRENT_USER\Software\%CompanyName%)

Registry.CreateKey(HKEY_CURRENT_USER, SessionVar.Expand("Software\\%CompanyName%"));

Modify Registry (Delete Key: HKEY_CURRENT_USER\Software\%CompanyName%)

Registry.DeleteKey(HKEY_CURRENT_USER, SessionVar.Expand("Software\\%CompanyName%"));

Modify Registry (Set Value: HKEY_CURRENT_USER\Software\%CompanyName% - My Value = Value Data)

Registry.SetValue(HKEY_CURRENT_USER, SessionVar.Expand("Software\\%CompanyName%"), "My Value", "Value Data", REG_SZ);

Modify Registry (Delete Value: HKEY_CURRENT_USER\Software\%CompanyName% - My Value)

Registry.DeleteValue(HKEY_CURRENT_USER, SessionVar.Expand("Software\\%CompanyName%"), "My Value");

Read from Registry (%RegistryVar% = HKEY_CURRENT_USER\Software\%CompanyName%\YourValue)

RegistryVar = Registry.GetValue(HKEY_CURRENT_USER, SessionVar.Expand("Software\\%CompanyName%"), "My Value", true);

-- To create a session variable to hold the data, you would use:
SessionVar.Set("%RegistryVar%", RegistryVar);

Services

Continue Service (Display name = My Service)

Service.Continue("My Service", "");

Create Service (%AppDir%\MyService.exe (Display name = Service Name | Key name = Service Name)

Service.Create(SessionVar.Expand("%AppFolder%\\MyService.exe"), "Service Name", "Service Name", SERVICE_WIN32_OWN_PROCESS, false, SERVICE_DEMAND_START, SERVICE_ERROR_NORMAL, 0, nil, nil, "", "");

Delete Service (Display name = My Service)

Service.Delete("My Service", "");

Pause Service (Display name = My Service)

Service.Pause("My Service", "");

Query Service (%ServiceStat% = Status Of (Display name = My Service))

Since this action returns a number, it really doesn't make sense to store the result in a session variable.

ServiceStat = Service.Query("My Service", "");

Start Service (Display name = My Service)

Service.Start("My Service", "", nil);

Stop Service (Display name = My Service)

-- Stops the service with a maximum wait time of 5 seconds.
Service.Stop("My Service", "", 5);

Shortcuts

Create Shortcut (%DeskTop%\My Shortcut -> %AppDir%\Yourfile.htm)

Shell.CreateShortcut(Shell.GetFolder(SHF_DESKTOP), "My Shortcut", SessionVar.Expand("%AppFolder%\\Yourfile.htm"), "", "", "", 0, SW_SHOWNORMAL, nil, "");

Remove Shortcut (%DeskTop%\My Shortcut)

Shell.DeleteShortcut(Shell.GetFolder(SHF_DESKTOP), "My Shortcut");

Strings

Count Delimited Strings (%NumStrings% = number of strings in a,b,c, delimiter = ,)

The concept of delimited strings has been replaced with a new feature part of Lua called tables. The equivalent action when the strings are stored as table entries is:

NumStrings = Table.Count(my_table);

Find String (%FindStringResult% = Position of str in Source string here)

If you need to perform a reverse find, you can use the String.ReverseFind action.

FindStringResult = String.Find("Source string here", "str", 1, false);

-- If you want to store the result in a session variable, you would use:
SessionVar.Set("%FindStringResult%", FindStringResult);

Format Number (Format: 25.43; Store in: %FormatResult%; Round)

If you need to truncate the string, you can use the String.TrimRight action.

FormatResult = Math.Round(25.43, 1);

-- If you want to store the result in a session variable, you would use:
SessionVar.Set("%FormatResult%", FormatResult);

Get Delimited String (%StringItem% = string 0 in a,b,c, delimiter = ,)

The concept of delimited strings has been replaced with a new feature part of Lua called tables. The equivalent action script when the strings are stored in a numerically indexed table is:

-- If the strings are stored in a numerically indexed table, you can simply reference the index
-- of the table that contains the string.
-- For example, lets take the table tbMyTable containing {"a","b","c"}:
-- Create the table.
tbMyTable = {"a","b","c"};

-- You can reference the value using:
tbMyTable[2]

Left String (%LeftStringResult% = left-most 5 characters of "Source string here")

LeftStringResult = String.Left("Source string here", 5);

-- If you want to store the result in a session variable, you would use:
SessionVar.Set("%LeftStringResult%", LeftStringResult);

Length of String (%LengthStringResult% = length of string "Source string here")

LengthStringResult = String.Length("Source string here");

-- If you want to store the result in a session variable, you would use:
SessionVar.Set("%LengthStringResult%", LengthStringResult);

Mid String (%MidStringResult% = mid 6 characters of "Source string here" starting at 5)

MidStringResult = String.Mid("Source string here", 5, 6);

-- If you want to store the result in a session variable, you would use:
SessionVar.Set("%MidStringResult%", MidStringResult);

Parse Path (%PathPart% = Drive part of C:\Folder1\Folder2\filename.ext)

-- This action splits the path into its separate components
tbPathPart = String.SplitPath("C:\\Folder1\\Folder2\\filename.ext");

-- To get the drive, you would use: tbPathPart.Drive
-- To get all of the folders, you would use: tbPathPart.Folder
-- To get the filename, you would use: tbPathPart.Filename
-- To get the extension you would use: tbPathPart.Extension

-- So if you wanted the drive and folders, you could create a new variable
-- by concatenating the values like this:
strNewPath = tbPathPart.Drive..tbPathPart.Folder

-- If you need to expand a session variable, you can use the SessionVar.Expand action.
-- If you need to create a new session variable, you can use the SessionVar.Set action.

Right String (%RightStringResult% = right-most 5 characters of "Source string here")

RightStringResult = String.Right("Source string here", 5);

-- If you want to store this in a session variable, you would use:
SessionVar.Set("%RightStringResult%", RightStringResult);

Text Files

To work with text files in Setup Factory 9, you must read them into either a string, or a table rather than working directly with the file. Once you are done, you would simply write back the modified string or table to the text file. Note that version 6.0's indexes were zero-based while Setup Factory 9's are one-based.

Count Text Lines (%LineCount% = number of lines in "C:\Dir 1\File 1.txt")

-- Read the text file into a table.
tbText = TextFile.ReadToTable("C:\\Dir 1\\File 1.txt");

-- Count the number of table entries and store the result in LineCount.
LineCount = Table.Count(tbText);

-- If you want the value in a session variable, you can use the SessionVar.Set action.

Delete Text Line (0 from "C:\Dir 1\File 1.txt")

-- Read the text file into a table.
tbText = TextFile.ReadToTable("C:\\Dir 1\\File 1.txt");

-- Remove the first line of the text file.
result = Table.Remove(tbText, 1);

-- To write the table back out to the text file, you would use:
TextFile.WriteFromTable("C:\\Dir 1\\File 1.txt", tbText, false);

Find Text Line (%LineFoundPos% = line number of "find this text" in C:\Dir 1\File1.txt)

Most of the time your goal is to find every line that contains the search text. While the Setup Factory 6.0 action only returned the first line found, this example shows how to find the first line found as well as all other occurrences.

-- Read the text file into a table.
tbText = TextFile.ReadToTable("C:\\Dir 1\\File 1.txt");

-- Create an empty table to hold the indexes of all line numbers where the search string was found.
tbSearchIndexes = {};

-- Loop through the text file table line by line.
for index, value in pairs(tbText) do
-- Check if the line contains the target string.
nFoundIndex = String.Find(value, "hey", 1, false);

-- Check to see if the string was found.
if (nFoundIndex ~= -1) then
-- The value was found.
-- Count the number of items in tbSearchIndexes.
nCount = Table.Count(tbSearchIndexes);

-- Insert the index of the text file where the search string was found
-- in the Search index table, tbSearchIndexes.
Table.Insert(tbSearchIndexes, nCount + 1, index);

-- At this point, you can also break out of the for loop using: break; if you wanted
-- to stop at the first item.
end
end

-- You can then loop through the table of found indexes and do what you like, or access the
-- first value tbSearchIndexes[1]
for index, line in pairs(tbSearchIndexes) do
-- Insert your code here. For example:
Dialog.Message("Indexes", "The search string was found at line: "..line);
end

-- If you want the first line number stored in a session variable, you would use:
SessionVar.Set("%LineFoundPos%", tbSearchIndexes[1]);

Get Text Line (%TextFileLine% = line 2 in "C:\Dir 1\File1.txt")

Since the most common way to work with text files is with tables, you would simply access the index in the table that corresponds to the line number.

-- Read the text file into a table.
tbText = TextFile.ReadToTable("C:\\Dir 1\\File 1.txt");

-- Since version 6.0 was zero based, you want to access the 3rd table index in this example:
TextFileLine = tbText[3];

-- If you want the string to be stored in a session variable. You would add:
SessionVar.Set("%TextFileLine%", TextFileLine);

Insert Text Line (Insert "Add this line to file" into "C:\Dir 1\File1.txt" at position 0)

If your text file is stored in a table, you would use the following method:

-- Read the text file into a table.
tbText = TextFile.ReadToTable("C:\\Dir 1\\File 1.txt");

-- Insert the line into the table at the first position.
Table.Insert(tbText, 1, "Add this line to file");

-- Write the text file back out.
TextFile.WriteFromTable("C:\\Dir 1\\File 1.txt", tbText, false);

Read Text File (%FileReadVar% = Contents of %SrcDir%\MyFile.ext)

To read the text file contents to a string:

-- To read the text file into a string variable FileReadVar:
FileReadVar = TextFile.ReadToString(_SourceFolder.."\\MyFile.ext");

-- If you want the string to be stored in a session variable. You would add:
SessionVar.Set("%FileReadVar%", FileReadVar);

Or to read the text file contents to a table:

-- To read the text file into the FileReadVar table:
tbFileReadVar = TextFile.ReadToTable(_SourceFolder.."\\MyFile.txt");

Write to Log File (Text to write)

SetupData.WriteToLogFile("Text to write\r\n", true);

Write to Text File ("Your data here" to %SrcDir%\MyFile.ext)

If the contents to write are within a string:

-- If the contents are within a string.
TextFile.WriteFromString(_SourceFolder.."\\MyFile.ext", "Your data here", false);

-- Or using the source folder session variable:
TextFile.WriteFromString(SessionVar.Expand("%SourceFolder%\\MyFile.ext"), "Your data here", false);

Or if the contents to write are within a table:

-- If the contents are within a table:
TextFile.WriteFromTable(_SourceFolder.."\\MyFile.ext", mytable, false);

-- Or using the source folder session variable:
TextFile.WriteFromTable(SessionVar.Expand("%SourceFolder%\\MyFile.ext"), mytable, false);

Variables

Assign Value (%CustomVar% = Default)

If your variable is a session variable, the equivalent action would be:

SessionVar.Set("%CustomVar%", "Default");

Or if you simply want to assign a value to a Lua variable, you would use:

CustomVar = "Default";

Generate Random Value (%RandomVar% = Number between 2 and 10)

You may also find you need to use the Math.RandomSeed action.

RandomVar = Math.Random(2, 10);

-- If you want the value to be stored in a session variable. You would add:
SessionVar.Set("%RandomVar%", RandomVar);

Get Disk Space (%DiskSpace% = Disk Space(C:))

-- Gets the disk space for the drive and returns the value in Megabytes.
DiskSpace = Drive.GetFreeSpace("C:");

-- If you need the value in bytes, you would just perform the calculation.
DiskSpace = DiskSpace * 1024 * 1024;

-- If you want the value to be stored in a session variable. You would add:
SessionVar.Set("%DiskSpace% ", DiskSpace);


What Is Converted

Importing Setup Factory 6.0 Projects

Overview What Is Converted What Is Not Converted (Gotcha's) Converting Actions

In general both the Archive and CD-ROM file lists, their properties, and many other settings will be converted to their equivalent Setup Factory 9 settings.

This section will outline all of the information that gets converted from Setup Factory 6.0 to Setup Factory 9. For a list of options that will not be converted please see the next section, What Is Not Converted.

This topic covers the conversion in the following areas of a Setup Factory 6.0 project:

  • General Design

  • Screens (not converted)

  • Actions

  • Archive and CD-ROM Files

  • Packages

  • Uninstall

  • Project Settings

General Design

The majority of the settings in Setup Factory 6.0's General Design area will be converted. Below is a detailed list of these conversions:

Product Info Tab:

  1. The variable values on the Product Info tab in Setup Factory 6.0 will be converted to Session Variables in Setup Factory 9, located on the Project Settings dialog.

Settings Tab:

  1. The “Create an installation log file” and other log file settings are all converted to Setup Factory 9 on the Logs tab of the Project Settings dialog.

  2. The “Run setup in silent mode” setting is converted to the “Start in silent” mode option in Setup Factory 9, located on the Advanced tab of the Project Settings dialog.

  3. The “Application title” is converted to the %WindowTitle% session variable located on the Session Variables tab of the Project Settings dialog.

  4. The variable defaults %AppDir% and %SCFolderTitle% are converted to the session variables %AppFolder% and %AppShortcutFolderName% on the Session Variables tab of the Project Settings dialog.

Languages Tab:

  1. The languages that are supported in the Setup Factory 6.0 project will be listed as supported languages in the converted project. If there is currently no language message file for the converted language, the text “Same as Default Language” will appear in place of the message file path. The message strings in the language files are not converted due to the changes to screens and other messages required by the setup.

Serial Numbers Tab:

  1. All serial number lists are converted from version 6.0 to 9 and available on the Serial Numbers tab of the Security dialog. The Security dialog can be accessed by choosing Project > Serial Numbers... from the program menu.

Primer Files Tab:

  1. All Primer files are converted from Setup Factory 6.0 to the Setup Factory 9 project and can be found on the Primer Files tab located on the Resources dialog. The Resources dialog can be accessed from the Resources program menu. Primer files are now extracted to %TempLaunchFolder% instead of %TempLaunchDir%, however the resultant directory is the same.

Screens

No screens or screen actions are converted from the Setup Factory 6.0 project to Setup Factory 9.

Actions

Project Actions

The project action events have been renamed to “On Startup,” “On Pre Install,” “On Post Install” and “On Shutdown.” All actions on Setup Factory 6.0's project events will be converted as action script comments on these newly named events. These must be recreated using the new Setup Factory 9 action script. You can use the Converting Actions topic as a reference to find the equivalent actions in version 9.

Archive and CD-ROM Files

All of the Archive and CD-ROM files and their properties (with the exception of file conditions) are converted from Setup Factory 6.0 to Setup Factory 9. However in Setup Factory 9, the CD-ROM tab is now labeled the “External” tab.

Packages

All packages and localized messages will be converted from the Setup Factory 6.0 project to their equivalent Setup Factory 9 values. Below is a detailed description of their conversion:

  1. The value defined as the “Package name” in the Setup Factory 6.0 project will be converted to the unique “Package ID”. This value will also be used as the “Display name” value.

  2. The package's description is converted to the corresponding value in version 9.

  3. The “Default value” setting in Setup Factory 6.0 is converted to the equivalent state of the “Install this package” setting in Setup Factory 9. If the TRUE radio button was selected, the “Install this package” will be checked.

  4. For localized packages, each “Package name” value will be converted to the “Display name” value for the selected language. The localized description is converted in the same manner.

Uninstall

Almost all of the uninstall settings are converted to Setup Factory 9. All of the Setup Factory 9's uninstall settings can be found under the Uninstall program menu. Below is a detailed list of the conversions:

Settings

  1. The “Include an uninstall program” setting in Setup Factory 6.0 is converted to the state of the “Create uninstall” setting in Setup Factory 9.

  2. The “Control panel description” in Setup Factory 6.0 is converted to the value in the “Description” field on the Control Panel tab of the Uninstall Settings dialog.

  3. The “Unique registry key” value in Setup Factory 6.0 is converted to the value in the “Unique registry key” field on the Control Panel tab of the Uninstall Settings dialog.

  4. The “Configuration file” value is converted to the value in the “Configuration filename” field on the Settings tab of the Uninstall Settings dialog.

  5. The “Create uninstall icon in shortcut folder” setting is converted to the state of the check box labeled “Create uninstall shortcut in Start menu > AppFolder.” This setting can be found on the Shortcut tab of the Uninstall Settings dialog.

  6. The “Shortcut icon description” string is converted to the “Description” string on the Shortcut tab of the Uninstall Settings dialog.

  7. If the “Use external icon file” check box is checked in the Setup Factory 6.0 project, the “Custom” icon mode will be selected in the converted project. The “External icon path” value that accompanies the previous setting is converted to the value in the “Icon path” field in the converted project. Both of these settings can be found on the Shortcut tab of the Uninstall Settings dialog.

Uninstall Actions

As with project actions, no uninstall actions are converted, however they are brought over as comments so you can recreate them using the new Setup Factory 9 action script. All of Setup Factory's uninstall events can be accessed by selecting Uninstall > Actions... from the program menu. You can use the Converting Actions topic as a reference for converting your actions script.

  1. Actions located on the “Before Uninstalling” event will be converted as comments on the On Startup event of the uninstall.
  2. Actions located on the “After Uninstalling” event will be converted as comments on the On Shutdown event of the uninstall.

Project Settings

The majority of Setup Factory 6.0's project settings are converted. These converted values can be accessed in Setup Factory 9 by choosing Publish > Settings from the program menu.

Build Settings

  1. The “Output folder”, “Setup file name” and “Output file segment size” in Setup Factory 6 are converted to their equivalent settings in Setup Factory 9. These can be found on the Setup File tab of the Build Settings dialog.

  2. The “Run Before Build” and “Run After Build” settings are converted to the settings on the Pre/Post Build tab of the Build Settings dialog in Setup Factory 9.

Design-time Constants

All design-time constants are brought over to the Constants tab of the Build Settings dialog in Setup Factory 9.


What Is Not Converted

Importing Setup Factory 6.0 Projects

Overview What Is Converted What Is Not Converted (Gotcha's) Converting Actions

As stated in the previous section, both the Archive and CD-ROM file lists and many other project settings will be converted from your Setup Factory 6.0 project to Setup Factory 9. However given the subtle and dramatic differences between Setup Factory 6.0 and Setup Factory 9, some options cannot be converted, most notably among these are actions and screens.

This topic outlines the elements of a Setup Factory 6.0 project that are not converted automatically. Choose one of the areas below for a description of its non-converted content:

  • Actions

  • Screens

  • General Design

  • Runtime Modules

  • Project Settings

  • File Properties

  • Uninstall

  • Preferences

  • Gotcha's

Actions

Actions will not be converted from Setup Factory 6.0 to Setup Factory 9. Given the vastly different way in which actions and variables are handled in Setup Factory 9, as opposed to Setup Factory 6.0, a conversion between the two is next to impossible.

In order to make the conversion process easier for you, all of the actions from your Setup Factory 6.0 project (except screen actions) will be converted as comments on the appropriate events in the converted Setup Factory 9 project. In cases where there is no one-to-one conversion between events (as in the uninstall events) the action code from Setup Factory 6.0 will be converted to the most appropriate Setup Factory 9 event. You can use the Converting Actions topic as a reference for converting your actions script.

Screens

Screens and screen actions will not be converted from Setup Factory 6.0 to Setup Factory 9. Given that all of the language translations are encapsulated in each screen, the importing of screens were impossible. Another complexity involved in the conversion was the introduction of project themes that are applied to all screens in the setup.

General Design

Settings Tab:

  1. The “Verify archive before installing” option is not converted. In Setup Factory 9, the archive will always be verified for single setups. If a multi-segment install is created, this option is automatically disabled.

  2. The “Progress screen image” is not converted. In Setup Factory 9, the progress screen can be configured as any other install screen. This screen can be found on the While Installing tab of the screen manager.

  3. The “Show Setup Factory logo on initial splash screen” is not converted because this feature no longer exists in Setup Factory 9.

Languages Tab:

  1. While each language that was supported by the version 6.0 project will be listed as supported in the converted Setup Factory 9 project, the internal messages of the language module will not be converted. This is due to the difference in messages required for the new screens and feature set.

Runtime Modules

The runtime modules included in the project are not converted. In Setup Factory 9 runtime modules were replaced with the new feature called Dependency Modules. While runtime modules were installed with your setup files, dependency modules are detected and installed at the beginning of the setup, before your application files are installed. Runtime modules in version 6.0 often contained multiple technologies, while in Setup Factory 9 they were designed to be stand alone modules that can be installed in any order you wish.

Project Settings

Directories Tab:

The folders defined as your base directories are not converted. Base directories are not explicitly set in Setup Factory 8.0 and have instead been replaced by internal logic that makes these decisions based on what makes most sense.

File Properties

Conditions Tab:

The “Run-time install condition” and “Build-time include conditions” are not converted to Setup Factory 9. Setup Factory 9 offers a user friendly check box tree for selecting the supported operating system. For non-operating system conditions the Setup Factory 6.0 condition has been replaced with a Lua script that will determine the outcome. These must be recreated.

Build-time include conditions have been replaced by the addition of Build Configurations in Setup Factory 9. This allows you to define different types of builds, such as debug and release builds, all with their own design-time constants and output settings.

Uninstall

Settings Tab:

  1. The “Wizard image” setting in Setup Factory 6.0 is not converted to Setup Factory 9. Setup Factory 9 allows additional screens to be created in the uninstall. As with the install screens, these can also be themed.

Preferences

The preference settings will not be converted from Setup Factory 6.0 to Setup Factory 9 since they are program wide, not project specific. The project converter only converts those options that are project specific.

Gotcha’s

  1. System requirements do not need to be handled through action conditions any longer. In Setup Factory 9, system requirements are defined on the Requirements tab located on the Project Settings dialog.

  2. In addition to the new action script in Setup Factory 9, variables have changed in Setup Factory 9. Any variables that are used for display purposes or destinations for files are now called session variables. Another type of variable mainly used in action script is called a Lua variable.

  3. If you have used a particular language module in Setup Factory 6.0 and converted your project, there may not be a language message file available for that language. In this case, the text “Same as Default Language” will appear in place of the message file path on the Languages tab. If a language message file is currently not available, you can certainly create one yourself by translating the messages to the desired language. All language files are in .XML format can be found in the Languages directory located within the main program directory. Simply make a copy of the file and start translating.


Import Registry Key/Values

Overview

The Import Registry Key/Values dialog allows you to select Registry keys or values from your development system so they can be automatically converted into Registry actions that will recreate its structure.

Sub keys only

Recreate the sub keys of the selected Registry key using Setup Factory Registry actions. Only the sub keys will be recreated, not their values.

Values only

Recreate the values of the selected Registry key using Setup Factory Registry actions.

Sub keys and values

Recreate both the values and sub keys of the selected Registry key using Setup Factory Registry actions.

Recurse sub keys

Recurse all of the sub keys of the selected Registry key when importing the selected Registry key.


Insert File Reference

Overview

The insert file reference dialog allows you to select a file from your install so that the proper session variables are used when referencing it. The file being referenced can be on the archive tab, external tab or a primer file. If the target file currently doesn't exist in your project, you can immediately add it to your project from this dialog.

Archive files

A list of the files currently added to the archive tab of your project. You can select a file and click OK to insert the file's installed path reference.

External files

A list of the files currently added to the external tab of your project. You can select a file and click OK to insert the file's installed path reference into the action code window.

Primer files

A list of the files currently added as primer files in your project. You can select a file and click OK to insert the file's installed path reference into the action code window. Primer files are always installed to directory stored in %TempLaunchFolder%.

Filename filter:

The filter you want to use for the insert file reference list. You can use the * and ? wildcards in this field to only include file names that match a specific pattern. For example, to only show executables, you can specify *.exe as the filter. You can also configure multiple filters using the OR character "|". For example, to only show executables and text files, you can specify *.exe|*.txt as the filter.

Refresh

Refreshes the file reference list. This is used to refresh the file list after specifying a filename filter.

Add File...

Opens a file browse dialog where you can select a file that currently doesn't exist in your project that you want to reference. The selected file will be added to your project given its type (archive, external or primer file) and its reference will be inserted into the action code window when you click OK.


Application.Exit Examples

Application.Exit

Application.Exit (

number ReturnCode = 0 )

Example 1

Application.Exit();

Immediately exits the installer.

Example 2

Application.Exit(4);

Immediately exits the installer and returns 4 as a custom return code to the calling process.

Example 3

-- Ask the user if they really want to exit
nChoice = Dialog.Message("Confirm Exit", "Are you sure you wish to exit?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON2);

-- If yes was chosen, exit the installer
if nChoice == 6 then
Application.Exit();
end

Confirm with the user that they wish to exit. If the choice is confirmed, exit the install, otherwise do nothing.


Application.ExitScript Examples

Application.ExitScript

Application.ExitScript (

)

Example 1

Application.ExitScript();

Terminates the currently running script.

Example 2

if (bTerminateScript) then
-- The script should be terminated.
Application.ExitScript();
end

If the boolean variable "bTerminateScript" is set to true, then the script is terminated.

Example 3

-- Get the CRC value from the 'secret' file.
SecretCRC = File.GetCRC("C:\\secret_directory\\secret_file.ext");

-- Check the returned CRC value against the expected value.
if (SecretCRC ~= 123456789) then
-- The values didn't match, terminate the script.
Application.ExitScript();
end

Checks the CRC value of a 'secret file'. If the returned value does not match the expected value, the script is terminated.


Application.GetInstallLanguage Examples

Application.GetInstallLanguage

table Application.GetInstallLanguage (

)

Example 1

tInstallLanguage = Application.GetInstallLanguage();

Retrieves the primary and secondary install language, and stores this information in a table called "tInstallLanguage". This information can be accessed by referencing tInstallLanguage.Primary and tInstallLanguage.Secondary.

Example 2

-- Retrieve the Install Language
tInstallLanguage = Application.GetInstallLanguage();

-- Check if the install language is english (English = 9)
if tInstallLanguage.Primary == 9 then
-- install language is english
Dialog.Message("Install Language", "Your install language is English!");
else
-- install language is not english
Dialog.Message("Install Language", "Your install language is not English!");
end

Retrieves the install language, compares the primary ID to the value representing English (9), and displays an appropriate message.


Application.GetLastError Examples

Application.GetLastError

number Application.GetLastError (

)

Example 1

nError = Application.GetLastError();

Gets the error code for the last action that was performed, and stores it in a variable named "nError."

Tip: Starting a variable name with "n" is a technique that programmers use to help themselves remember that a variable is supposed to contain a numeric value.

Example 2

errmsg = "Error #" .. Application.GetLastError().. " in " .. Debug.GetEventContext();

Uses the concatenation operator (..) to form an error message containing the last error code and the current event context and stores the error message in a variable named "errmsg."

Example 3

-- Print the specified file.
File.Print(SessionVar.Expand("%AppFolder%\\Readme.txt"));

--Check to see if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Prints the file "Readme.txt" located in the user's application directory (%AppFolder%). If the action fails, the error code message is displayed in a dialog message.

Note: In order to expand the session variable %AppFolder% in an action, the action SessionVar.Expand must be used.

Example 4

-- Confirm that the program executable should be launched.
result = Dialog.Message("Confirm", "Are you sure you would like to launch the application?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- If the user clicked the Yes button.
if (result == IDYES) then

-- Run the installation file.
File.Run(SessionVar.Expand("%AppFolder%\\myprogram.exe"), "", "", SW_SHOWNORMAL, false);

-- Check to see if an error occurred when launching the file.
error = Application.GetLastError();

-- If an error occurred, display an error message to the user.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
end

Asks the user if they would like to run the application. If they click the Yes button, the application file will be launched using the File.Run action. If the action fails, the error code message is displayed in a dialog message.


Application.GetWndHandle Examples

Application.GetWndHandle

number Application.GetWndHandle (

)

Example 1

handle = Application.GetWndHandle();

Gets the numeric window handle for the installation window and stores it in the variable "handle."

Example 2

-- Get the installation window handle.
handle = Application.GetWndHandle();

-- Hide the installation window.
Window.Hide(handle);

-- Sleep for 3 seconds.
Application.Sleep(3000);

-- Show the installation window.
Window.Show(handle);

Gets the numeric window handle for the installation window and stores it in the variable "handle." The window handle is then used to hide the window for 3 seconds.


Application.IgnoreLastError Examples

Application.IgnoreLastError

Application.IgnoreLastError (

)

Example 1

Application.IgnoreLastError();

Ignores the last setup error that occurred. This action must be called from either the On Install Error or On Uninstall Error event.


Application.LoadActionPlugin Examples

Application.LoadActionPlugin

Application.LoadActionPlugin (

string Filename )

Example 1

Application.LoadActionPlugin(SessionVar.Expand("%AppFolder%\\Clipboard.lmd"));

Loads the "Clipboard" action plugin into the current install.

Example 2

Application.LoadActionPlugin(Plugin_To_Load);

Loads the action plugin referenced in the variable "Plugin_To_Load" into the current install.


Application.LoadScript Examples

Application.LoadScript

Application.LoadScript (

string Filename )

Example 1

Application.LoadScript(_TempFolder.."\\AddedFunctionality.lua");

Loads and executes the external script file called "AddedFunctionality.lua" that is currently located in the user's Temp folder. This script file will be executed once during the application.

Example 2

Application.LoadScript(_SourceFolder.."\\MyScript.lua");

Loads and executes the script file called "MyScript.lua."

Note: _SourceFolder is a built-in variable that contains the path to the folder where the installation executable is located.


Application.LoadValue Examples

Application.LoadValue

string Application.LoadValue (

string Section,

string Key )

Example 1

first_name = Application.LoadValue("User Info", "First Name");

Loads the current value of the "First Name" key in the "User Info" section, and stores it in a variable called "first_name".

Example 2

address = Application.LoadValue("Company", "Address");

Looks up the value of "Address" in the "Company" section, and stores it in a variable named "address".

Example 3

user_name = "";
-- Loop until a valid user name is entered or the user cancels.
while (user_name == "") and (user_name ~= "CANCEL") do
--Prompt the user for their user name.
user_name = Dialog.Input("User Information", "Please enter your user name:", "", MB_ICONQUESTION);

-- If the user does not enter any text, display an error message. The loop will continue from the beginning.
if user_name == "" then
result = Dialog.Message("Error", "Your information could not be processed as entered. Please try again.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If the user entered a valid user name and didn't cancel, store the value in the Registry.
elseif user_name ~= "CANCEL" then
Application.SaveValue("Your_User_Name", "Your_Key", user_name);

-- Check to see if there was an error saving.
error = Application.GetLastError();
end
end

-- If the user didn't cancel and there was no error saving,
-- Load the user name from the registry and display a welcome dialog.
if (user_name ~= "CANCEL") and (error == 0) then
loaded_username = Application.LoadValue("Your_User_Name", "Your_Key");

-- If the value loaded successfully.
if (Application.GetLastError() == 0) then
result = Dialog.Message("Hello", "Welcome "..loaded_username.."!", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
end

Prompts the user for a user name using the Dialog.Input action and then saves the name in the Registry. The name is then loaded from the Registry and displayed in a dialog.


Application.Minimize Examples

Application.Minimize

Application.Minimize (

)

Example 1

Application.Minimize();

Minimizes the installer's window to the task bar.


Application.Restore Examples

Application.Restore

Application.Restore (

)

Example 1

Application.Restore();

Restores the installer's window to the size and position it had before it was minimized.


Application.RunScriptFile Examples

Application.RunScriptFile

Application.RunScriptFile (

string Filename )

Example 1

Application.RunScriptFile(_TempFolder.."\\AddedFunctionality.lua");

Executes the external script file called "AddedFunctionality.lua" that is currently located in the user's Temp folder.

Example 2

Application.RunScriptFile(_SourceFolder.."\\MyScript.lua");

Runs the script file called "MyScript.lua."

Note: _SourceFolder is a built-in variable that contains the path to the folder where the installation executable is located.


Application.SaveValue Examples

Application.SaveValue

Application.SaveValue (

string Section,

string Key,

string Value )

Example 1

Application.SaveValue("User Info", "First Name", first_name);

Saves the value that is currently in the variable "first_name" into a section called "User Info" and a key called "First Name".

Example 2

Application.SaveValue("Company", "Address", "123 Bannatyne Avenue");

Saves the value "123 Bannatyne Avenue" into the "Address" key of the "Company" section.

Example 3

user_name = "";
-- Loop until a valid user name is entered or the user cancels.
while (user_name == "") and (user_name ~= "CANCEL") do
--Prompt the user for their user name.
user_name = Dialog.Input("User Information", "Please enter your user name:", "", MB_ICONQUESTION);

-- If the user does not enter any text, display an error message. The loop will continue from the beginning.
if user_name == "" then
result = Dialog.Message("Error", "Your information could not be processed as entered. Please try again.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If the user entered a valid user name and didn't cancel, store the value in the Registry.
elseif user_name ~= "CANCEL" then
Application.SaveValue("Your_User_Name", "Your_Key", user_name);

-- Check to see if there was an error saving.
error = Application.GetLastError();
end
end

-- If the user didn't cancel and there was no error saving,
-- Load the user name from the registry and display a welcome dialog.
if (user_name ~= "CANCEL") and (error == 0) then
loaded_username = Application.LoadValue("Your_User_Name", "Your_Key");

-- If the value loaded successfully.
if (Application.GetLastError() == 0) then
result = Dialog.Message("Hello", "Welcome "..loaded_username.."!", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
end

Prompts the user for a user name using the Dialog.Input action and then saves the name in the Registry. The name is then loaded from the Registry and displayed in a dialog.


Application.SetInstallLanguage Examples

Application.SetInstallLanguage

Application.SetInstallLanguage (

number Primary,

number Secondary )

Example 1

Application.SetInstallLanguage(0,2);

Sets the install language to the user's system default language.


Application.SetLastError Examples

Application.SetLastError

Application.SetLastError (

number ErrorCode )

Example 1

Application.SetLastError(0); -- set the last error to "no error occurred"

Sets the last error code to 0, signalling that "the last action was successful." (The text after the "--" in this example is just a comment.)

Example 2

Application.SetLastError(3245);

Sets the last error code to 3245.

Example 3

-- Create custom error table
tCustomErrors = {};
tCustomErrors[10001] = "Under 13 Years of Age";
tCustomErrors[10002] = "Numeric Age > 0 Required";

-- Prompt user for their age
sAge = Dialog.Input("User Input", "Enter your age");

-- Convert age string to number
nAge = String.ToNumber(sAge);

-- Check for error one criteria
if nAge < 13 then
Application.SetLastError(10001);
end

-- Check for error two criteria
if nAge <= 0 then
Application.SetLastError(10002);
end

-- Get the last error
nLastError = Application.GetLastError();

-- was the last error 'success' (0)?
if nLastError == 0 then
--No error occured, do something here
else
--An error occured
Dialog.Message("Error", "Error (" .. nLastError .. "): " .. tCustomErrors[nLastError] .. ".", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

This example uses custom error codes to determine if the conditions fail and to display a more appropriate error message.


Application.Sleep Examples

Application.Sleep

Application.Sleep (

number Time )

Example 1

Application.Sleep(1000);

Makes the installer sleep for 1 second.

Example 2

Application.Sleep(5200);

Makes the installer sleep for 5.2 seconds.


Crypto.Base64DecodeFromFile Examples

Crypto.Base64DecodeFromFile

Crypto.Base64DecodeFromFile (

string Source,

string Destination )

Example 1

-- Decodes a base64-encoded text file located in the the user's Temp folder and stores the result as a binary file.
-- The base-64-encoded text file was previously encoded using the Crypto.Base64EncodeToFile action.
Crypto.Base64DecodeFromFile(_TempFolder .."\\myfile_encoded.txt", _TempFolder .."\\myfile_decoded.txt");

-- Check to see if an error occurred in the Crypto.Base64DecodeFromFile action.
-- If an error occurred, display the error message.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Decodes a base64-encoded text file located in the user's Temp folder and stores the result as a binary file.


Crypto.Base64DecodeFromString Examples

Crypto.Base64DecodeFromString

Crypto.Base64DecodeFromString (

string Text,

string Filename )

Example 1

-- base64-encodes a small binary file and store the result in encoded_string
encoded_string = Crypto.Base64EncodeToString("C:\\myfile.exe");

-- Check to see if an error occurred using the Crypto.Base64EncodeToString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Display the contents of the string, just to show you what it looks like.
Dialog.Message("This is what the encoded string looks like:", encoded_string);

-- Decode the base64-encoded string and store the result as a binary file.
Crypto.Base64DecodeFromString(encoded_string, _TempFolder.."\\myfile_decoded_string.txt");

-- Check to see if an error occurred using the Crypto.Base64DecodeFromString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Base64 encodes a binary file and stores the result in a string. The string is then decoded and shown in a dialog message.


Crypto.Base64EncodeToFile Examples

Crypto.Base64EncodeToFile

Crypto.Base64EncodeToFile (

string Source,

string Destination,

number LineLen = 76 )

Example 1

-- Takes a binary file located in the user's Temp folder and stores the result as a base64-encoded text file,
-- also located in the user's Temp folder.
-- This file can then be decoded using the Crypto.Base64DecodeFromFile action.
Crypto.Base64EncodeToFile(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_encoded.txt");

-- Check to see if an error occurred in the Crypto.Base64EncodeToFile action.
-- If an error occurred, display the error message.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Takes a binary file located in the user's Temp folder and stores the result as a base64-encoded text file, also located in the user's Temp folder.


Crypto.Base64EncodeToString Examples

Crypto.Base64EncodeToString

string Crypto.Base64EncodeToString (

string Source,

number LineLen = 76 )

Example 1

-- Returns the contents of a small binary file as a base64-encoded string.
encoded_string = Crypto.Base64EncodeToString("C:\\MyFolder\\myfile.txt");

-- Check to see if an error occurred using the Crypto.Base64EncodeToString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
-- Display the contents of the string, just to show you what it looks like.
Dialog.Message("This is what the encoded string looks like:", encoded_string);

-- Decode the base64-encoded string and store the result as a binary file.
Crypto.Base64DecodeFromString(encoded_string, _TempFolder.."\\myfile_decoded_string.txt");

-- Check to see if an error occurred using the Crypto.Base64DecodeFromString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Encodes the contents of a small binary file as a base64-encoded string and shows what it looks like using a dialog message. The string is then decoded to a text file in the user's temp folder.


Crypto.BlowfishDecrypt Examples

Crypto.BlowfishDecrypt

Crypto.BlowfishDecrypt (

string Source,

string Destination,

string Key )

Example 1

-- Create a blowfish-encrypted copy of a text file in the user's temp folder
Crypto.BlowfishEncrypt(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_blowfished.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishEncrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Decrypts the blowfish-encrypted file.
Crypto.BlowfishDecrypt(_TempFolder.."\\myfile_blowfished.txt", _TempFolder.."\\myfile_blowfish_decrypted.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishDecrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Open the decrypted file to see its contents.
File.Open(_TempFolder.."\\myfile_blowfish_decrypted.txt");

Creates a blowfish-encrypted copy of a text file in the user's temp folder and then decrypts and opens the file.


Crypto.BlowfishDecryptString Examples

Crypto.BlowfishDecryptString

string Crypto.BlowfishDecryptString (

string Text,

string Key )

Example 1

sDecryptedString = Crypto.BlowfishDecryptString(sEncryptedString, sKey);

Decrypts the string 'sEncryptedString' using the key stored in 'sKey' and stores the decrypted string in the variable 'sDecryptedString'.

Example 2

-- Initialize Registration/Access variables
bRegistrationRequired = true;
bAllowAccess = false;

-- Initialize registry action variables
nMainKey = HKEY_CURRENT_USER;
sSubKey = "SOFTWARE\\Your_Product\\Registration";
sUserNameValue = "UserName";
sSerialValue = "Serial";
sMD5CheckValue = "CheckKey";
sRegisterKeyValue = "RegKey";
bAutoExpand = true;

-- if the user's registration info was stored in the Windows Registry
-- (in the form of blowfish-encrypted strings), decrypt it
if Registry.DoesKeyExist(nMainKey, sSubKey) then
-- Key exists, pull values from registry
sUserName = Registry.GetValue(nMainKey, sSubKey, sUserNameValue, bAutoExpand);
sSerial = Registry.GetValue(nMainKey, sSubKey, sSerialValue, bAutoExpand);
sMD5Check = Registry.GetValue(nMainKey, sSubKey, sMD5CheckValue, bAutoExpand);
sRegisterKey = Registry.GetValue(nMainKey, sSubKey, sRegisterKeyValue, bAutoExpand);

if (sUserName ~= "") and (sSerial ~= "") and (sMD5Check) and (sRegisterKey ~= "") then
-- All four values are present, perform check
sUserNameDecrypted = Crypto.BlowfishDecryptString(sUserName, sRegisterKey);
sSerialDecrypted = Crypto.BlowfishDecryptString(sSerial, sRegisterKey);

if (Crypto.MD5DigestFromString(sUserNameDecrypted) .. Crypto.MD5DigestFromString(sSerialDecrypted)) == sMD5Check then
-- MD5 check passed, we don't need to register
bRegistrationRequired = false;
-- allow access
bAccessAllowed = true;
end
end
end

if bRegistrationRequired then
-- Registration is required
sUserName = Dialog.Input("UserName", "Please enter your username:");
if sUserName ~= "CANCEL" and sUserName ~= "" then
-- User didn't press cancel, get serial
sSerial = Dialog.Input("UserName", "Please enter your serial number:");

if sSerial ~= "CANCEL" and sSerial ~= "" then
-- user didn't press cancel, continue.

-- get install date time in format JULIANsecondsMINUTEShours
sInstallDateTime = System.GetDate(DATE_FMT_JULIAN) .. System.GetTime(TIME_FMT_SEC) ..System.GetTime(TIME_FMT_MIN) .. System.GetTime(TIME_FMT_HOUR);

-- Generate HTTP Submit variables
sURL = "http://www.yourdomain.com/register_app.php"
tSubmitTable = {user = sUserName, serial = sSerial, installed = sInstallDateTime};
nMethod = SUBMITWEB_POST;
nTimeout = 20;
nPort = 80;
tAuth = nil;
tProxy = nil;

-- Submit to web (structure of returned string: UserNameMD5SerialMD5::Key)
sReturnedData = HTTP.Submit(sURL, tSubmitTable, nMethod, nTimeout, nPort, tAuthData, tProxyData);

if sReturnedData == "-1" or sReturnedData == "" then
-- An error occured, deny access
bAccessAllowed = false;
else
-- No error occured, cut apart string
nDelimiterPosition = String.Find(sReturnedData, "::", 1, false);
-- Get everything before the ::
sMD5Check = String.Mid(sReturnedData, 1, nDelimiterPosition - 1);

-- Get everything after the ::
sKey = String.Mid(sReturnedData, nDelimiterPosition + 2, -1);

-- Assign the registry values
Registry.SetValue(nMainKey, sSubKey, sUserNameValue, Crypto.BlowfishEncryptString(sUserName, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sSerialValue, Crypto.BlowfishEncryptString(sSerial, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sMD5CheckValue, sMD5Check, REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sRegisterKeyValue, sKey, REG_SZ);

-- set register variable to false (so the user isn't prompted to enter info again)
bRegistrationRequired = false;
-- display thank-you message
Dialog.Message("SUCCESS!", "Thank-you for registering. Enjoy the product!");

-- allow access
bAccessAllowed = true;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
end

if not bAccessAllowed then
Dialog.Message("ERROR", "Invalid registration information provided.", MB_OK, MB_ICONSTOP);
Application.Exit();
end

Reads information from the registry and decrypts it. If the information does not exist, the above script will interact with a web-based php script (http://www.yourdomain.com/register_app.php) to verify a serial number. For this example, the following php script will function:

<?
// Check for post data
if ($_POST)
{
// Initialize user array in format "Username"=>"Serial"
$user_array = array(
"John Doe"=>"abc-def-ghi",
"Jane Smith"=>"123-456-789"
);

// Get info from post variables
$user = $_POST['user'];
$serial = $_POST['serial'];
$installed = $_POST['installed'];

// Step through the user array
foreach($user_array as $username=>$serialnumber)
{
// Compare current item to the posted information
if(($user==$username) AND ($serial==$serialnumber))
{
// The current user matched, return info and exit
echo md5($user).md5($serial).'::'.$installed;
exit;
}
}

// If this script makes it this far, nothing matched, return error code
echo -1;
}
else
{
// no post data was sent, return error code
echo -1;
}
?>

Note: The above php script must be hosted on a PHP-enabled web host, and be called from your application using either an HTTP.Submit or an HTTP.SubmitSecure action.


Crypto.BlowfishEncrypt Examples

Crypto.BlowfishEncrypt

Crypto.BlowfishEncrypt (

string Source,

string Destination,

string Key )

Example 1

-- Create a blowfish-encrypted copy of a text file in the user's temp folder
Crypto.BlowfishEncrypt(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_blowfished.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishEncrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Open the encrypted file to see its contents.
File.Open(_TempFolder.."\\myfile_blowfished.txt");

Creates a blowfish-encrypted copy of a text file in the user's temp folder and then opens that file in the user's default text editor.


Crypto.BlowfishEncryptString Examples

Crypto.BlowfishEncryptString

string Crypto.BlowfishEncryptString (

string Text,

string Key,

number LineLen = 0 )

Example 1

sEncryptedString = Crypto.BlowfishEncryptString(sTextToEncrypt, sSecretKey);

Encrypts the text stored in 'sTextToEncrypt' with the key stored in 'sSecretKey', and stores the result in 'sEncryptedString'.

Example 2

-- Initialize Registration/Access variables
bRegistrationRequired = true;
bAllowAccess = false;

-- Initialize registry action variables
nMainKey = HKEY_CURRENT_USER;
sSubKey = "SOFTWARE\\Your_Product\\Registration";
sUserNameValue = "UserName";
sSerialValue = "Serial";
sMD5CheckValue = "CheckKey";
sRegisterKeyValue = "RegKey";
bAutoExpand = true;

-- if the user's registration info was stored in the Windows Registry
-- (in the form of blowfish-encrypted strings), decrypt it
if Registry.DoesKeyExist(nMainKey, sSubKey) then
-- Key exists, pull values from registry
sUserName = Registry.GetValue(nMainKey, sSubKey, sUserNameValue, bAutoExpand);
sSerial = Registry.GetValue(nMainKey, sSubKey, sSerialValue, bAutoExpand);
sMD5Check = Registry.GetValue(nMainKey, sSubKey, sMD5CheckValue, bAutoExpand);
sRegisterKey = Registry.GetValue(nMainKey, sSubKey, sRegisterKeyValue, bAutoExpand);

if (sUserName ~= "") and (sSerial ~= "") and (sMD5Check) and (sRegisterKey ~= "") then
-- All four values are present, perform check
sUserNameDecrypted = Crypto.BlowfishDecryptString(sUserName, sRegisterKey);
sSerialDecrypted = Crypto.BlowfishDecryptString(sSerial, sRegisterKey);

if (Crypto.MD5DigestFromString(sUserNameDecrypted) .. Crypto.MD5DigestFromString(sSerialDecrypted)) == sMD5Check then
-- MD5 check passed, we don't need to register
bRegistrationRequired = false;
-- allow access
bAccessAllowed = true;
end
end
end

if bRegistrationRequired then
-- Registration is required
sUserName = Dialog.Input("UserName", "Please enter your username:");
if sUserName ~= "CANCEL" and sUserName ~= "" then
-- User didn't press cancel, get serial
sSerial = Dialog.Input("UserName", "Please enter your serial number:");

if sSerial ~= "CANCEL" and sSerial ~= "" then
-- user didn't press cancel, continue.

-- get install date time in format JULIANsecondsMINUTEShours
sInstallDateTime = System.GetDate(DATE_FMT_JULIAN) .. System.GetTime(TIME_FMT_SEC) ..System.GetTime(TIME_FMT_MIN) .. System.GetTime(TIME_FMT_HOUR);

-- Generate HTTP Submit variables
sURL = "http://www.yourdomain.com/register_app.php"
tSubmitTable = {user = sUserName, serial = sSerial, installed = sInstallDateTime};
nMethod = SUBMITWEB_POST;
nTimeout = 20;
nPort = 80;
tAuth = nil;
tProxy = nil;

-- Submit to web (structure of returned string: UserNameMD5SerialMD5::Key)
sReturnedData = HTTP.Submit(sURL, tSubmitTable, nMethod, nTimeout, nPort, tAuthData, tProxyData);

if sReturnedData == "-1" or sReturnedData == "" then
-- An error occured, deny access
bAccessAllowed = false;
else
-- No error occured, cut apart string
nDelimiterPosition = String.Find(sReturnedData, "::", 1, false);
-- Get everything before the ::
sMD5Check = String.Mid(sReturnedData, 1, nDelimiterPosition - 1);

-- Get everything after the ::
sKey = String.Mid(sReturnedData, nDelimiterPosition + 2, -1);

-- Assign the registry values
Registry.SetValue(nMainKey, sSubKey, sUserNameValue, Crypto.BlowfishEncryptString(sUserName, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sSerialValue, Crypto.BlowfishEncryptString(sSerial, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sMD5CheckValue, sMD5Check, REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sRegisterKeyValue, sKey, REG_SZ);

-- set register variable to false (so the user isn't prompted to enter info again)
bRegistrationRequired = false;
-- display thank-you message
Dialog.Message("SUCCESS!", "Thank-you for registering. Enjoy the product!");

-- allow access
bAccessAllowed = true;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
end

if not bAccessAllowed then
Dialog.Message("ERROR", "Invalid registration information provided.", MB_OK, MB_ICONSTOP);
Application.Exit();
end

Reads information from the registry and decrypts it. If the information does not exist, the above script will interact with a web-based php script (http://www.yourdomain.com/register_app.php) to verify a serial number. For this example, the following php script will function:

<?
// Check for post data
if ($_POST)
{
// Initialize user array in format "Username"=>"Serial"
$user_array = array(
"John Doe"=>"abc-def-ghi",
"Jane Smith"=>"123-456-789"
);

// Get info from post variables
$user = $_POST['user'];
$serial = $_POST['serial'];
$installed = $_POST['installed'];

// Step through the user array
foreach($user_array as $username=>$serialnumber)
{
// Compare current item to the posted information
if(($user==$username) AND ($serial==$serialnumber))
{
// The current user matched, return info and exit
echo md5($user).md5($serial).'::'.$installed;
exit;
}
}

// If this script makes it this far, nothing matched, return error code
echo -1;
}
else
{
// no post data was sent, return error code
echo -1;
}
?>

Note: The above php script must be hosted on a PHP-enabled web host, and be called from your application using either an HTTP.Submit or an HTTP.SubmitSecure action.


Crypto.MD5DigestFromFile Examples

Crypto.MD5DigestFromFile

string Crypto.MD5DigestFromFile (

string Filename )

Example 1

-- calculate the MD5 message digest for a file
-- note: edit this path so it points to an actual file :)
file = "C:\\MyFolder\\MyFile.htm";
strMD5 = Crypto.MD5DigestFromFile(file);

if (strMD5 ~= "") then
Dialog.Message("MD5DigestFromFile","The MD5 digest for "..file.." is:\r\n\r\n"..strMD5);
else
err = Application.GetLastError();
Dialog.Message("Arooga! Arooga!","ERROR "..err..": ".._tblErrorMessages[err]);
end

Calculates the MD5 message digest for a file and shows the result in a dialog message.


Crypto.MD5DigestFromString Examples

Crypto.MD5DigestFromString

string Crypto.MD5DigestFromString (

string Text )

Example 1

-- Calculate the MD5 message digest for the user's name and display it in a message
strName = Dialog.Input("", "What is your name?", "", MB_ICONQUESTION);
strDigitalSignature = Crypto.MD5DigestFromString(strName);
Dialog.Message("The digital signature for your name is:",strDigitalSignature);

Prompts for the user's name and then generates the MD5 message digest for it and shows it in a dialog message.

Example 2

--[[ note: our app allows the user to password-protect it. If the user
chose to enable password-protection, they were prompted for
a password, we appended a suffix to it (to help prevent
dictionary attacks), and the MD5 digest for the resulting
password + suffix was stored in the Registry.]]

--[[ get the digest that was stored in the Registry at HKEY_CURRENT_USER\Software\SuperDooperApp
note: this was calculated when the user supplied the password,
before it was stored ]]
reg_md5 = Registry.GetValue(HKEY_CURRENT_USER, "Software\\SuperDooperApp", "password")
-- the value only exists when the app is password-protected
if reg_md5 ~= "" then
--[[ ask the user for the password they supplied when they enabled
the password protection feature ]]
pw = Dialog.Input("", "Please enter your password:");
--[[ we added "!$" to their password before it was stored,
to help make the user's password safe from dictionary attacks ]]
pw = pw .. "!$"
-- calculate the MD5 message digest for the password + suffix
pw_md5 = Crypto.MD5DigestFromString(pw);
-- exit the app if the password digests don't match
if pw_md5 ~= reg_md5 then
Dialog.Message("", "Sorry, invalid password!");
Application.Exit();
end
end

Given that the MD5 message digest for a password was previously stored in the Registry, a user is prompted for the password and it is compared to the current password input from the user. If the message digests do not match, the application exits.


Crypto.Rot13 Examples

Crypto.Rot13

string Crypto.Rot13 (

string Text )

Example 1

-- encrypt the user's name
strName = Dialog.Input("", "What is your name?", "", MB_ICONQUESTION);

-- rot13 encrypt the name
strEncrypted = Crypto.Rot13(strName);
Dialog.Message("Your name, rot13 encrypted:",strEncrypted);

-- rot13 decrypt the name
strDecrypted = Crypto.Rot13(strEncrypted);
Dialog.Message("And now rot13 decrypted:",strDecrypted);

Encrypts a user name using "rot13", displays it in a dialog message, then rot13 decrypts it and displays it in a dialog message.


Debug.Clear Examples

Debug.Clear

Debug.Clear (

)

Example 1

Debug.Clear();

Clears the contents of the debug window.

Example 2

-- Show the debug window.
Debug.ShowWindow(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print("6 + 2 = "..total.."\r\n");

-- Ask if the debug window should be cleared.
result = Dialog.Message("Question", "Do you want to clear the debug window?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- If the user clicks the Yes button, clear the debug window.
-- If the user clicks the No button, leave it.
if result == IDYES then
Debug.Clear();
end

Outputs some text to the debug window and asks if the window should be cleared using a Dialog.Message action. If they click yes, the debug window will be cleared. If they click no, no action will be taken.


Debug.GetEventContext Examples

Debug.GetEventContext

string Debug.GetEventContext (

)

Example 1

context = Debug.GetEventContext();

Gets the current device context string and stores it in a variable named "context." For example, "Welcome > On Next"

Example 2

errmsg = "Error #" .. Application.GetLastError().. " in " .. Debug.GetEventContext();

Uses the concatenation operator (..) to form an error message containing the last error code and the current event context and stores the error message in a variable named "errmsg."

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Get the event context and print it to the debug window.
context = Debug.GetEventContext();
Debug.Print(context);

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.GetTraceMode Examples

Debug.GetTraceMode

boolean Debug.GetTraceMode (

)

Example 1

trace_mode = Debug.GetTraceMode();

Stores the current trace mode (true/false) in a variable named "trace_mode."

Example 2

if Debug.GetTraceMode() then Dialog.Message("", "Trace mode is on!") end

Displays a dialog message saying "Trace mode is on!" if trace mode is currently enabled.

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Get the event context and print it to the debug window.
context = Debug.GetEventContext();
Debug.Print(context);

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.Print Examples

Debug.Print

Debug.Print (

string Text )

Example 1

Debug.Print("Help button clicked");

Prints "Help button clicked" to the debug window. (You could put this action in the "On Help" event for a Help button to find out if the event's actions are being performed.)

Example 2

Debug.Print("On Next event fired: " .. Debug.GetEventContext());

Prints a debug message consisting of the string "On Next event fired: " followed by the current event context.

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Get the event context and print it to the debug window.
context = Debug.GetEventContext();
Debug.Print(context);

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.SendToFile Examples

Debug.SendToFile

number Debug.SendToFile (

string Filename,

boolean Overwrite = true )

Example 1

nResult = Debug.SendToFile("C:\\MyLog.txt", true);

Sends the output to the text file "MyLog.txt", overwriting any existing copy and returns the result in the variable nResult.


Debug.SetTraceMode Examples

Debug.SetTraceMode

Debug.SetTraceMode (

boolean Enable = true )

Example 1

Debug.SetTraceMode(true); -- turn it on

Turns trace mode on. (The text after the "--" in this example is just a comment.)

Example 2

Debug.SetTraceMode(false); -- turn it off

Turns trace mode off.

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Get the event context and print it to the debug window.
context = Debug.GetEventContext();
Debug.Print(context);

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.ShowWindow Examples

Debug.ShowWindow

Debug.ShowWindow (

boolean Show )

Example 1

Debug.ShowWindow(true);

Shows the debug window.

Example 2

Debug.ShowWindow(false);

Hides the debug window.

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Get the event context and print it to the debug window.
context = Debug.GetEventContext();
Debug.Print(context);

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Dialog.ComboBox Examples

Dialog.ComboBox

string Dialog.ComboBox (

string Title,

string Prompt,

table Items,

string DefaultItem,

boolean SortItems = false,

boolean Editable = false,

number Icon = MB_ICONQUESTION )

Example 1

-- The combo box items table.
tbItems = {"Apple", "Orange", "Pear"};

-- Show the dialog combo box.
strSelected = Dialog.ComboBox("Select Lunch","Please select the desired fruit:",tbItems,"Apple",false,false,MB_ICONQUESTION);

if ((strSelected ~= "") and (strSelected ~= "CANCEL")) then
Dialog.Message("Result", "The chosen fruit is "..strSelected);
end

Prompts the user to select a fruit from a combo box on a dialog, and shows the result in a dialog message if they clicked OK.


Dialog.FileBrowse Examples

Dialog.FileBrowse

table Dialog.FileBrowse (

boolean FileOpen,

string Title,

string DefaultFolder,

string FileFilters = "All Files (*.*)|*.*|",

string Filename = "",

string FileExtension = "",

boolean MultipleSelect = false,

boolean FileMustExist = false )

Example 1

files = Dialog.FileBrowse(true, "Open File", _ProgramFilesFolder, "Text File (*.txt)|*.txt|All Files(*.*)|*.*|", "", "", false, false);

Prompts the user to select a single text file in their Program Files folder, and stores the path to the file they select in a table named "files."

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's "Program Files" folder.

Example 2

-- Display a single-selection file browse dialog
result = Dialog.FileBrowse(true, "Load File", _DesktopFolder, "Microsoft Word Document (*.doc)|*.doc|All Files (*.*)|*.*|", "", "", false, true);

-- If CANCEL was not chosen, then let's get the file path
if (result[1] ~= "CANCEL") then
Dialog.Message("You chose the following file", result[1]);
end

Prompts the user to select a single Word document file (.doc) browsing from their Desktop folder, and stores the path to the file they select in a table named "result." If the cancel button was not chosen, a dialog message is displayed showing the file path that is stored in the table.

Example 3

-- Prompt the user to select files to add to the zip archive.
archive_files = Dialog.FileBrowse(true, "Files to Add", _DesktopFolder, "All Files (*.*)|*.*|", "", "dat", true, false);

-- Check to see if an error occurred, or the user cancelled.
if (archive_files[1] ~= "CANCEL") and (archive_files ~= nil) then

-- Show the status dialog.
StatusDlg.Show();

-- Add the chosen files to the zip archive.
Zip.Add(_DesktopFolder.."\\NewArchive.zip", archive_files, true, "", 5, nil, false);

-- Get the error code of the zip.add action.
error = Application.GetLastError();

-- Hide the status dialog.
StatusDlg.Hide();

-- If it succeeded, display a success message and open the folder. Otherwise display the error message.
if (error == 0) then
Dialog.Message("Success", "The files were successfully archived.", MB_OK, MB_ICONINFORMATION);

-- Open the folder where the zip file was created.
File.ExploreFolder(_DesktopFolder, SW_SHOWNORMAL);
else
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

A file browse dialog is displayed allowing the user to select files they would like added to a Zip archive. The selected files are then added to a Zip archive created on their desktop. If the process is successful, a success message is displayed. If there was an error, the error code message is shown.


Dialog.FolderBrowse Examples

Dialog.FolderBrowse

string Dialog.FolderBrowse (

string Prompt,

string DefaultFolder )

Example 1

folder_path = Dialog.FolderBrowse("Select Folder", _SourceFolder);

Prompts the user to select a single folder from the "source folder" on the CD-ROM and stores the path to the selected folder in a variable named "folder_path."

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 2

-- Display a folder browse dialog
storage_path = Dialog.FolderBrowse("Store Files In", _ProgramFilesFolder);

-- If CANCEL was not chosen, then let's get the folder path
if (storage_path ~= "CANCEL") then
Dialog.Message("You chose the following folder", storage_path);
end

Asks the user what path to store files in, letting them browse for a folder starting from the Program Files folder. The resulting path is stored in storage_path. The second block of code is a check to see if the user pressed the cancel button. If they didn't, a dialog message is displaying showing the folder that was selected.

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files folder.

Example 3

-- Allow the user to select a directory to unzip the files.
target_folder = Dialog.FolderBrowse("Select a Folder", "C:\\");

-- Check to see if the user cancelled or an error occurred.
if (target_folder ~= "CANCEL") and (target_folder ~= "") then
-- Gets a list of the contents of a zip file.
zip_contents = Zip.GetContents(_SourceFolder.."\\Info.zip", true);

-- Get the error code of the last action.
error = Application.GetLastError();

-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Take the table and turn it into a string with newlines for displaying.
zip_contents_display = Table.Concat(zip_contents, "\r\n", 1, TABLE_ALL);

-- Ask the user if they are sure they would like to unzip the contents.
result = Dialog.Message("Information", "The following files will be unzipped:\r\nClick the Cancel button to abort the process.\r\n\r\n"..zip_contents_display, MB_OKCANCEL)

-- If the user clicked Ok, unzip the files.
if (result == IDOK) then
-- Show the status dialog.
StatusDlg.Show();
-- Extract the contents of the Zip file.
Zip.Extract(_SourceFolder.."\\Info.zip", {"*.*"}, target_folder, true, true, "", ZIP_OVERWRITE_NEVER, nil);

-- Check the error code for the last action.
error = Application.GetLastError();

-- Hide the status dialog.
StatusDlg.Hide();

-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Errror", tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
Dialog.Message("Success", "The unzipping was successful.", MB_OK, MB_ICONINFORMATION);
end
end
end
end

This example first prompts the user to select a folder using the Dialog.FolderBrowse action. This folder will be used to unzip the files to. The user is then presented with a dialog containing the names of the files that will be unzipped and allows them to abort the process. If the user clicks OK, the files are unzipped to the folder they selected. Notification will be given at the end of the process as to whether or not the procedure was successful.


Dialog.Input Examples

Dialog.Input

string Dialog.Input (

string Title,

string Prompt,

string DefaultText = "",

number Icon = MB_ICONQUESTION )

Example 1

full_name = Dialog.Input("Welcome", "Please enter your full name:");

Prompts the user for their full name, and stores their answer in a variable named "full_name."

Example 2

strAnswer = Dialog.Input("Question "..nQuestion, strQuestion, "", MB_ICONQUESTION);

Asks the user the question contained in the variable strQuestion. The concatenation operator (..) is used to include the question number in the dialog's title bar. The user's answer (which they can type into the dialog's input field) is stored in strAnswer when they click OK.

Tip: The "n" and "str" prefixes used for the variables in this example are a naming technique that programmers use to help themselves remember whether a variable contains a number or a string.

Example 3

name = "";
-- Loop until a valid full name is entered or the user cancels.
while (name == "") and (name ~= "CANCEL") do
-- Prompt the user for their full name
name = Dialog.Input("Personal Information", "Please enter your full name:", "", MB_ICONQUESTION);

-- If the user does not enter any text, display an error message. The loop will continue from the beginning
if name == "" then
result = Dialog.Message("Error", "Your information could not be processed as entered. Please try again.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If the user entered a valid name and didn't cancel, display a welcome message.
elseif name ~= "CANCEL" then
result = Dialog.Message("Welcome", "Welcome "..name.."!", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
end

This example uses a while loop to prompt the user for their full name using a Dialog.Input action. If the user does not enter any text as input, an error message will appear and the input dialog will be displayed again. The loop will only be exited if they enter a name or press the cancel button.


Dialog.MaskedInput Examples

Dialog.MaskedInput

table Dialog.MaskedInput (

string Title = "",

string Prompt,

string Mask,

string DefaultText = "",

number Icon = MB_ICONQUESTION,

string PlaceHolder = " " )

Example 1

postal_code = Dialog.MaskedInput("", "What is your Postal Code?", ">#> #>#", "", MB_ICONQUESTION, " ");

Asks the user for their postal code, making sure that they enter it in the correct format (three capital letters, three numbers, and a space, like this: A9A 9A9), and stores the result in table called postal_code. The raw data can be accessed by referencing postal_code.Data and the string as it was displayed can be accessed by referencing postal_code.Displayed.

Example 2

-- Set the flag variable.
pass = false;

while (not pass) do
-- Prompt the user for their telephone number.
phone = Dialog.MaskedInput("Personal Information", "Please enter your telephone number:", "(###) ###-####", "##########", MB_ICONQUESTION, "#");

-- If there wasn't an error and the user didn't cancel, try to validate the number.
if (phone ~= nil) then
-- Search for the placeholder character "#".
search_result = String.Find(phone.Data, "#", 1, false);

-- If the placeholder character wasn't found...
if (search_result == -1) then
-- Display the telephone number in a dialog.
Dialog.Message("Information", "The telephone number "..phone.Displayed.." will be entered in our records.", MB_OK, MB_ICONINFORMATION);

-- Set the flag to exit the loop.
pass = true;
else
-- Tell the user that the phone number entered was not complete.
Dialog.Message("Notice", "The telephone number entered was not complete. Please re-enter the number.", MB_OK, MB_ICONINFORMATION);
end
else
-- There was an error or the user cancelled. Exit the loop.
pass = true;
end
end

Prompts the user to enter their telephone number using the Dialog.MaskedInput action. In order to help the user enter the information, the telephone mask is used. The placeholder character and default text uses the "#" character. A validation is performed on the user input that checks for the "#" character signalling an incomplete number. If its found, the user is prompted to re-enter the information. The loop will only be exited if the user enters a valid telephone number, or cancels. If they enter a valid number, a dialog is shown with their number as it was displayed.


Dialog.Message Examples

Dialog.Message

number Dialog.Message (

string Title,

string Text,

number Type = MB_OK,

number Icon = MB_ICONINFORMATION,

number DefaultButton = MB_DEFBUTTON1 )

Example 1

btn = Dialog.Message("Error!", "Unable to proceed.", MB_RETRYCANCEL);

Alerts the user that an error occurred and asks them if they want to retry or cancel. Depending on which button they click on, the value represented by the constant IDRETRY or IDCANCEL will be stored in the btn variable.

Example 2

Dialog.Message("Important", "The rain in Spain falls mainly on the plain.", MB_OK, MB_ICONEXCLAMATION);

Gives the user an important (okay, maybe not so important :) message, and waits for them to click the OK button before continuing.

Note: This example doesn't store the return value in a variable because it will always be IDOK. In cases like these, we say that the return value is ignored.

Example 3

ishappy = Dialog.Message("Prying Question #023", "Are you happy?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);

Asks the user if they're happy, with Yes and No buttons on the dialog. Since we're asking a question, the MB_ICONQUESTION icon is specified. To encourage happiness in our users, the Yes button is selected by default. The user's response is stored in the variable ishappy as one of two constants, IDYES or IDNO.

Example 4

-- Gets the path to the user's My Documents folder.
my_docs_path = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Check to see if the My Documents folder detection was successful.
if (Application.GetLastError() == 0)then

-- Search the user's My Documents folder for the file "Data.ini".
search_results = File.Find(my_docs_path, "Data.ini", true, false, nil);

--Check to see if an error occurred during the search. If it did, display the error message.
error = Application.GetLastError();
if error ~= 0 then
Dialog.Message("Error",_tblErrorMessages[error]);
else

-- If no files were found, notify the user.
if (search_results == nil) then
Dialog.Message("Notice", "Data.ini was not found in your My Documents folder.");

-- If files were found, display a dialog containing a list of their locations.
-- Also ask for deletion confirmation.
else
message = "Data.ini was found in the following location(s). Click OK to delete the file(s):\r\n\r\n";
for index, path in pairs(search_results) do
message = String.Concat(message, path.."\r\n");
end
proceed = Dialog.Message("File Search Results", message, MB_OKCANCEL, MB_ICONQUESTION, MB_DEFBUTTON1);

-- If the user clicked OK, delete all of the files found.
if proceed == IDOK then

-- Delete each file found in the search.
for index, path in pairs(search_results) do
File.Delete(path, false, false, false, nil);

-- Check to see if any errors occurred during the deletion.
if (Application.GetLastError() ~= 0) then
Dialog.Message("Error", "The file located at: "..path.." could not be deleted.");
end
end
end
end
end
end

This example uses the File.Find action to search for all copies of a particular INI file in the user's My Documents folder. If the file is found in more than one location, the user is presented with the list and asked if they wish to delete them using a Dialog.Message action. If they agree, each copy is deleted using the File.Delete action.


Dialog.PasswordInput Examples

Dialog.PasswordInput

string Dialog.PasswordInput (

string Title,

string Prompt,

number Icon = MB_ICONNONE )

Example 1

password = Dialog.PasswordInput("Enter Password", "Password:");

Asks the user for a password, and stores their answer in a variable called password.

Example 2

-- the correct password "valid"
real_password = "valid";

-- prompt the user to enter a password
user_password = Dialog.PasswordInput("Password", "Please enter the password: ", MB_ICONQUESTION);

-- compare the user's password to the correct password.
-- If the user supplies the wrong password, exit the program.
if real_password ~= user_password then
Application.Exit();
end

This example displays a dialog box requesting a password using the Dialog.PasswordInput action. For this example, the string "valid" is used as the password. Whatever the user types into this dialog box appears as *******. If the correct password "valid" is entered, the program runs normally. However if any other password is entered, the program will close.


Dialog.SplashImage Examples

Dialog.SplashImage

Dialog.SplashImage (

string MediaFile,

number Time = 0,

boolean AllowClickToSkip = true )

Example 1

Dialog.SplashImage(SessionVar.Expand("%TempLaunchFolder%\\indigorose_32bpp.png"), 5, false);

Displays the primer image file 'indigorose_32bpp.png' for five seconds before the installer loads. The user cannot click through this image.

Example 2

Dialog.SplashImage(sSplashImageFile, nTime, true);

Displays the image file stored in string 'sSplashImageFile' for a period of time specified in variable 'nTime'. The user can click through this image at any time.


Dialog.TimedMessage Examples

Dialog.TimedMessage

Dialog.TimedMessage (

string Title,

string Text,

number Time,

number Icon = MB_ICONINFORMATION )

Example 1

Dialog.TimedMessage("Oh oh...", "Waiting for a miracle", 5000, MB_ICONNONE);

Display a message that says "Waiting for a miracle" for 5 seconds, which is sure to instill confidence in your users.

Example 2

Dialog.TimedMessage("Security Check", "Performing retinal scan...", 6000, MB_ICONEXCLAMATION);

Display a message that says "Performing retinal scan..." for 6 seconds, with an exclamation mark icon on the dialog to make it seem even more important. (This message is most effective if, first, you tell the user to stare into the monitor and DON'T BLINK.)

Example 3

Dialog.TimedMessage("", "Meep meep", 1500, MB_ICONNONE);

Puts up a cryptic road runner impersonation for 1.5 seconds, with no text in the title bar.

Example 4

-- Get the installation's window handle.
handle = Application.GetWndHandle();

-- Hide the installer window.
Window.Hide(handle);

-- Presents a timed please wait dialog for 3 seconds.
Dialog.TimedMessage("Please Wait...", "Please be patient while processing.", 3000, MB_ICONNONE);

-- Show the installer window.
Window.Show(handle);

Hides the installation window while displaying a timed dialog message. Once the timed dialog has elapsed, the installer window is shown again.


DlgBillboard.AddImage Examples

DlgBillboard.AddImage

number DlgBillboard.AddImage (

number ControlID,

string FilePath,

number Position = -1 )

Example 1

nPos = DlgBillboard.AddImage(CTRL_BILLBOARD_01, _TempLaunchFolder.."\\new_image.png", -1);

Adds the image "new_image.png" at the end of the list of the billboard control whose ID is CTRL_BILLBOARD_01, and stores its insertion position in the variable "nPos."

Example 2

nPos = DlgBillboard.AddImage(CTRL_BILLBOARD_01, _TempLaunchFolder.."\\new_image2.png", 5);

Adds the image "new_image2.png" to the billboard control at position 5, and stores its insertion position in the variable "nPos."


DlgBillboard.DeleteImage Examples

DlgBillboard.DeleteImage

DlgBillboard.DeleteImage (

number ControlID,

number Position )

Example 1

DlgBillboard.DeleteImage(CTRL_BILLBOARD_02, 8);

Removes the image at position 8 from the billboard control whose ID is CTRL_BILLBOARD_02.

Example 2

DlgBillboard.DeleteImage(CTRL_BILLBOARD_01, -1);

Removes all images from the billboard control whose ID is CTRL_BILLBOARD_01.


DlgBillboard.FillFromFolder Examples

DlgBillboard.FillFromFolder

DlgBillboard.FillFromFolder (

number ControlID,

string FolderPath,

boolean EmptyFirst = false,

boolean Recurse = false )

Example 1

DlgBillboard.FillFromFolder(CTRL_BILLBOARD_01, "C:\\Extracted", true, false);

Fills the billboard control with all images found in the "Extracted" folder. Before adding the images, the control is emptied.

Example 2

DlgBillboard.FillFromFolder(CTRL_BILLBOARD_02, Shell.GetFolder(SHF_MYDOCUMENTS), false, true);

Adds all images recursively found in the user's 'My Documents' folder to the billboard control whose ID is CTRL_BILLBOARD_02.


DlgBillboard.GetCurrentImage Examples

DlgBillboard.GetCurrentImage

number DlgBillboard.GetCurrentImage (

number ControlID )

Example 1

nCurrent = DlgBillboard.GetCurrentImage(CTRL_BILLBOARD_01);

Gets the index of the current image in the billboard control with ID CTRL_BILLBOARD_01 and stores the result in the variable "nCurrent."


DlgBillboard.GetImageCount Examples

DlgBillboard.GetImageCount

number DlgBillboard.GetImageCount (

number ControlID )

Example 1

nTotal = DlgBillboard.GetImageCount(CTRL_BILLBOARD_01);

Gets the number of images in the billboard control with ID CTRL_BILLBOARD_01 and stores the result in a variable called "nTotal."


DlgBillboard.GetImagePath Examples

DlgBillboard.GetImagePath

string DlgBillboard.GetImagePath (

number ControlID,

number Position )

Example 1

-- Get the path to image 5.
path = DlgBillboard.GetImagePath(CTRL_BILLBOARD_01, 5);

-- Show the path in a dialog message.
Dialog.Message("Image Path", path);

Gets the path to the image at index 5 in the billboard control and shows its value in a dialog message.


DlgBillboard.GetPos Examples

DlgBillboard.GetPos

table DlgBillboard.GetPos (

number ControlID )

Example 1

tbPos = DlgBillboard.GetPos(CTRL_BILLBOARD_03);

Gets the current X, Y coordinates of the billboard control CTRL_BILLBOARD_03 and stores the results in a table called "tbPos." These values can be accessed by referencing tbPos.X and tbPos.Y.


DlgBillboard.GetProperties Examples

DlgBillboard.GetProperties

table DlgBillboard.GetProperties (

number ControlID )

Example 1

tProperties = DlgBillboard.GetProperties(CTRL_BILLBOARD_01);

Gets the properties from the billboard control CTRL_BILLBOARD_01 and stores them in table 'tProperties'.

Example 2

sFiles = "";
tbProps = DlgBillboard.GetProperties(CTRL_BILLBOARD_02);

if (tbProps) then
if (tbProps.ImageFiles) then
for index, path in pairs(tbProps.ImageFiles) do
sFiles = sFiles..path.."\r\n";
end
Dialog.Message("Image Files", sFiles);
end
end

Gets the properties from the billboard control CTRL_BILLBOARD_02 and stores them in table 'tbProps'. Then a dialog message is shown containing the paths of all of the image files in the control.


DlgBillboard.GetSize Examples

DlgBillboard.GetSize

table DlgBillboard.GetSize (

number ControlID )

Example 1

control_size = DlgBillboard.GetSize(CTRL_BILLBOARD_01);

Gets the pixel dimensions of the billboard control CTRL_BILLBOARD_01 and stores the width and height values in the "control_size" table. The dimensions can be accessed by referencing control_size.Width and control_size.Height.


DlgBillboard.GoToImage Examples

DlgBillboard.GoToImage

DlgBillboard.GoToImage (

number ControlID,

number Position )

Example 1

DlgBillboard.GoToImage(CTRL_BILLBOARD_03, 10);

Navigates to the image at position 10 in the billboard control whose ID is CTRL_BILLBOARD_03.


DlgBillboard.IsEnabled Examples

DlgBillboard.IsEnabled

boolean DlgBillboard.IsEnabled (

number ControlID )

Example 1

enabled = DlgBillboard.IsEnabled(CTRL_BILLBOARD_02);

Stores true in a variable named "enabled" if the billboard control is enabled, and false if it is disabled.

Example 2

b2Enabled = DlgBillboard.IsEnabled(CTRL_BILLBOARD_02);

Checks whether the billboard control is enabled or disabled, and sets the "b2Enabled" variable to either true or false accordingly.

Tip: Starting a variable name with "b" is a technique that programmers use to help themselves remember that a variable contains a boolean value.


DlgBillboard.IsVisible Examples

DlgBillboard.IsVisible

boolean DlgBillboard.IsVisible (

number ControlID )

Example 1

Visible = DlgBillboard.IsVisible(CTRL_BILLBOARD_01);

Checks whether the CTRL_BILLBOARD_01 billboard control is visible and stores true or false in a variable called "Visible."

Example 2

b2isVisible = DlgBillboard.IsVisible(CTRL_BILLBOARD_02);

Stores true in "b2isVisible" if the CTRL_BILLBOARD_02 billboard control is visible.

Tip: Starting a variable name with "b" is a technique that programmers use to help themselves remember that a variable contains a boolean value.


DlgBillboard.Navigate Examples

DlgBillboard.Navigate

DlgBillboard.Navigate (

number ControlID,

number NavigateType )

Example 1

DlgBillboard.Navigate(CTRL_BILLBOARD_01, BILLBOARD_NEXT);

Navigates to the next image in the billboard control whose ID is CTRL_BILLBOARD_01.


DlgBillboard.Pause Examples

DlgBillboard.Pause

DlgBillboard.Pause (

number ControlID )

Example 1

DlgBillboard.Pause(CTRL_BILLBOARD_01);

Pauses the billboard control whose ID is CTRL_BILLBOARD_01


DlgBillboard.Play Examples

DlgBillboard.Play

DlgBillboard.Play (

number ControlID )

Example 1

DlgBillboard.Play(CTRL_BILLBOARD_01);

Plays the billboard control whose ID is CTRL_BILLBOARD_01.


DlgBillboard.SetEnabled Examples

DlgBillboard.SetEnabled

DlgBillboard.SetEnabled (

number ControlID,

boolean Enabled = true )

Example 1

DlgBillboard.SetEnabled(CTRL_BILLBOARD_01, true);

Enables the billboard control whose ID is CTRL_BILLBOARD_01.

Example 2

DlgBillboard.SetEnabled(CTRL_BILLBOARD_02, false);

Disables the billboard control whose ID is CTRL_BILLBOARD_02.


DlgBillboard.SetPos Examples

DlgBillboard.SetPos

DlgBillboard.SetPos (

number ControlID,

number X,

number Y )

Example 1

DlgBillboard.SetPos(CTRL_BILLBOARD_01, 100, 150);

Sets the CTRL_BILLBOARD_01 billboard control's X coordinate to 100 pixels and the Y coordinate to 150.

Example 2

DlgBillboard.SetPos(CTRL_BILLBOARD_02, 0, 0);

Sets the CTRL_BILLBOARD_02 billboard control's X coordinate to 0 and the Y coordinate to 0. The billboard control will be moved to the upper left hand corner of the screen from its current position.


DlgBillboard.SetProperties Examples

DlgBillboard.SetProperties

DlgBillboard.SetProperties (

number ControlID,

table Properties )

Example 1

-- Create a table of the properties you want to set.
tbProps = {};
tbProps.Loop=true;
tbProps.Transitions=true;

-- Set the control's properties.
DlgBillboard.SetProperties(CTRL_BILLBOARD_01, tbProps);

Sets the CTRL_BILLBOARD_01 billboard control to loop and to have a transition effect between images.


DlgBillboard.SetSize Examples

DlgBillboard.SetSize

DlgBillboard.SetSize (

number ControlID,

number Width,

number Height )

Example 1

DlgBillboard.SetSize(CTRL_BILLBOARD_01, 400, 350);

Sets the CTRL_BILLBOARD_01 billboard control's width to 400 pixels and it's height to 350 pixels.

Example 2

DlgBillboard.SetSize(CTRL_BILLBOARD_02, DlgBillboard.GetSize(CTRL_BILLBOARD_02).Width + 200, DlgBillboard.GetSize(CTRL_BILLBOARD_02).Height + 100);

Increases the CTRL_BILLBOARD_02 billboard control's current width by 200 pixels and it's current height by 100 pixels. The DlgBillboard.GetSize action is used here to get the current size of the billboard control.


DlgBillboard.SetVisible Examples

DlgBillboard.SetVisible

DlgBillboard.SetVisible (

number ControlID,

boolean Visible = true )

Example 1

DlgBillboard.SetVisible(CTRL_BILLBOARD_03, true);

Makes the CTRL_BILLBOARD_03 billboard control visible.

Example 2

DlgBillboard.SetVisible(CTRL_BILLBOARD_01, false);

Hides the billboard control whose ID is CTRL_BILLBOARD_01.

Example 3

DlgBillboard.SetVisible(CTRL_BILLBOARD_05);

Makes the billboard control CTRL_BILLBOARD_05 visible.


DlgButton.GetProperties Examples

DlgButton.GetProperties

table DlgButton.GetProperties (

number ControlID )

Example 1

tProperties = DlgButton.GetProperties(CTRL_BUTTON_HELP);

Gets the properties for the help button on the current screen and stores the results in the table "tProperties."

Example 2

tButtonProperties = DlgButton.GetProperties(nControlID);

if not tButtonProperties.Visible then
tButtonProperties.Visible = true;
DlgButton.SetProperties(nControlID, tButtonProperties);
end

Gets the properties of the button whose id is stored in nControlID. If this button is currently not visible, it is made visible.


DlgButton.SetProperties Examples

DlgButton.SetProperties

DlgButton.SetProperties (

number ControlID,

table Properties )

Example 1

DlgButton.SetProperties(CTRL_BUTTON_HELP, tProperties);

Sets the properties of the help button to those contained in the table called "tProperties."

Example 2

DlgButton.SetProperties(CTRL_BUTTON_CANCEL, {Visible = false, Enabled = false});

Disables and hides the Cancel button on the current screen.

Example 3

tButtonProperties = DlgButton.GetProperties(nControlID);

if not tButtonProperties.Visible then
tButtonProperties.Visible = true;
DlgButton.SetProperties(nControlID, tButtonProperties);
end

Gets the properties of the button whose id is stored in nControlID. If this button is currently not visible, it is made visible using the DlgButton.SetProperties action.


DlgCheckBox.GetProperties Examples

DlgCheckBox.GetProperties

table DlgCheckBox.GetProperties (

number ControlID )

Example 1

tProperties = DlgCheckBox.GetProperties(CTRL_CHECK_BOX_01);

Gets the properties for the '01' Check Box Control on the current screen and stores the results in the table "tProperties."

Example 2

tCheckProperties = DlgCheckBox.GetProperties(nControlID);

if not tCheckProperties.Visible then
tCheckProperties.Visible = true;
DlgCheckBox.SetProperties(nControlID, tCheckProperties);
end

Gets the properties of the check box control whose id is stored in nControlID. If this control is not visible, it is made visible.


DlgCheckBox.SetProperties Examples

DlgCheckBox.SetProperties

DlgCheckBox.SetProperties (

number ControlID,

table Properties )

Example 1

DlgCheckBox.SetProperties(CTRL_CHECK_BOX_02, tProperties);

Sets the properties for the '02' Check Box control to those contained in the table "tProperties".

Example 2

DlgCheckBox.SetProperties(CTRL_CHECK_BOX_03, {Visible = false, Enabled = false});

Disables and hides the '03' Check Box Control on the current screen.

Example 2

tCheckProperties = DlgCheckBox.GetProperties(nControlID);

if not tCheckProperties.Visible then
tCheckProperties.Visible = true;
DlgCheckBox.SetProperties(nControlID, tCheckProperties);
end

Gets the properties of the check box control whose id is stored in nControlID. If this control is not visible, it is made visible.


DlgComboBox.AddItem Examples

DlgComboBox.AddItem

number DlgComboBox.AddItem (

number ControlID,

string ItemText )

Example 1

Line = DlgComboBox.AddItem(CTRL_COMBOBOX_01, "ItemText");

Inserts the item "ItemText" into the '01' combo box control at the appropriate position and stores the resulting line number in the number "Line".

Example 2

tItemsToAdd = {"David", "Shelly", "Billy", "Bob", "Tanya"};
DlgComboBox.RemoveItem(CTRL_COMBOBOX_02, -1);

for nIndex, sItem in pairs(tItemsToAdd) do
DlgComboBox.AddItem(CTRL_COMBOBOX_02, sItem);
end

Removes all items from the '02' combo box control, and adds a table of new items.


DlgComboBox.GetItemData Examples

DlgComboBox.GetItemData

string DlgComboBox.GetItemData (

number ControlID,

number Index )

Example 1

sData = DlgComboBox.GetItemData(CTRL_COMBOBOX_01, 2);

Gets the data from the second item in the combo box control with id CTRL_COMBOBOX_01 and stores it in string "sData".

Example 2

sItemData = DlgComboBox.GetItemData(nControlID, nIndex);

Gets the data of the index referenced in variable "nIndex" from the control whose id is stored in variable "nControlID". The data is stored in string "sItemData".


DlgComboBox.GetItemText Examples

DlgComboBox.GetItemText

string DlgComboBox.GetItemText (

number ControlID,

number Index )

Example 1

sText = DlgComboBox.GetItemText(CTRL_COMBOBOX_01, 2);

Gets the text from the second item in the combo box control with id CTRL_COMBOBOX_01 and stores it in string "sText".

Example 2

sItemText = DlgComboBox.GetItemText(nControlID, nIndex);

Gets the text of the index referenced in variable "nIndex" from the control whose id is stored in variable "nControlID". The text is stored in string "sItemText".


DlgComboBox.GetProperties Examples

DlgComboBox.GetProperties

table DlgComboBox.GetProperties (

number ControlID )

Example 1

combo_prop = DlgComboBox.GetProperties(CTRL_COMBOBOX_01);

Gets the properties from the 1st combo box and stores them in the table "combo_prop".

Example 2

-- function ToString () converts a boolean value (true/false)
-- to a string (True, False). If the value passed is not
-- of type boolean, the passed value is returned unchanged.
function ToString(Value)
-- Ensure value is type boolean
if type (Value) ~= "boolean" then
-- Value is not type boolean, return unchanged
return Value;
elseif Value then
-- Value is true, return string True
return "True";
else
-- Value is false, return string False
return "False";
end
end

-- Retrieve the properties from combo box control 02
tProperties = DlgComboBox.GetProperties(CTRL_COMBOBOX_02);

-- Show the Debug Window.
Debug.ShowWindow(true);

-- For each property in the table, do this
for Property, Value in pairs(tProperties) do
-- Output property to debug window
Debug.Print(Property .. ": " .. ToString(Value) .. "\r\n\r\n");
end

Gets the properties of the '02' combo box control and outputs them to the debug window. The function ToString is used to convert any boolean values to strings. If the function is passed a value that is not boolean, the value is returned unchanged.


DlgComboBox.InsertItem Examples

DlgComboBox.InsertItem

number DlgComboBox.InsertItem (

number ControlID,

number Index,

string ItemText )

Example 1

DlgComboBox.InsertItem(CTRL_COMBOBOX_02, 1, "I am an item, now in position 1!!");

Inserts an item into the '02' combo box control at position 1 with text "I am an item, now in position 1!!".

Example 2

DlgComboBox.InsertItem(nControlID, -1, sItem);

Inserts an item with item text stored in the variable "sItem" into the combo box control whose control ID is referenced in variable "nControlID". The item is inserted at the end of the list.


DlgComboBox.RemoveItem Examples

DlgComboBox.RemoveItem

DlgComboBox.RemoveItem (

number ControlID,

number Index )

Example 1

DlgComboBox.RemoveItem(CTRL_COMBOBOX_01, -1);

Removes all items from the '01' combo box control.

Example 2

DlgComboBox.RemoveItem(nControlID, 3);

Removes the third item from the combo box control whose control ID is referenced in nControlID.

Example 3

DlgComboBox.RemoveItem(nControlID, nIndex);

Removes the item whose index is referenced in variable "nIndex" from the combo box control whose control ID is referenced in nControlID.


DlgComboBox.SetItemData Examples

DlgComboBox.SetItemData

DlgComboBox.SetItemData (

number ControlID,

number Index,

string ItemData )

Example 1

DlgComboBox.SetItemData(CTRL_COMBOBOX_01, 2, "I'm number two!, YES, I'm number TWO!");

Sets the data in the second item in the combo box control with id CTRL_COMBOBOX_01 to "I'm number two!, YES, I'm number TWO!".

Example 2

DlgComboBox.SetItemData(nControlID, nIndex, sData);

Sets the data of the index referenced in variable "nIndex" for the control who's ID is referenced in variable "nControlID" to the string stored in "sData".


DlgComboBox.SetProperties Examples

DlgComboBox.SetProperties

DlgComboBox.SetProperties (

number ControlID,

table Properties )

Example 1

DlgComboBox.SetProperties(CTRL_COMBOBOX_01, tProperties);

Sets the properties of the '01' combo box control to those contained in the table called "tProperties."

Example 2

DlgComboBox.SetProperties(CTRL_COMBOBOX_02, {Visible = false, Enabled = false});

Disables and hides the '02' combo box control on the current screen.

Example 3

tProperties = DlgComboBox.GetProperties(nControlID);

if not tProperties.Visible then
tProperties.Visible = true;
DlgComboBox.SetProperties(nControlID, tProperties);
end

Gets the properties of the combo box control whose id is stored in nControlID. If this control is currently not visible, it is made visible using the DlgComboBox.SetProperties action.


DlgEditField.GetProperties Examples

DlgEditField.GetProperties

table DlgEditField.GetProperties (

number ControlID )

Example 1

tFoldEdit = DlgEditField.GetProperties(CTRL_EDIT_FOLDER);

Gets the properties for the 'folder' edit field control and stores them in table "tFoldEdit."

Example 2

-- function ToString () converts a boolean value (true/false)
-- to a string (True, False). If the value passed is not
-- of type boolean, the passed value is returned unchanged.
function ToString(Value)
-- Ensure value is type boolean
if type (Value) ~= "boolean" then
-- Value is not type boolean, return unchanged
return Value;
elseif Value then
-- Value is true, return string True
return "True";
else
-- Value is false, return string False
return "False";
end
end

-- Retrieve the properties from Edit control 01
tProperties = DlgEditField.GetProperties(CTRL_EDIT_01);

-- Show the Debug Window.
Debug.ShowWindow(true);

-- For each property in the table, do this
for Property, Value in pairs(tProperties) do
-- Output property to debug window
Debug.Print(Property .. ": " .. ToString(Value) .. "\r\n\r\n");
end

Gets the properties of the '01' edit field control and outputs them to the debug window. The function ToString is used to convert any boolean values to strings. If the function is passed a value that is not boolean, the value is returned unchanged.


DlgEditField.SetProperties Examples

DlgEditField.SetProperties

DlgEditField.SetProperties (

number ControlID,

table Properties )

Example 1

DlgEditField.SetProperties(nControlID, tProperties);

Sets the properties of the edit field control referenced in the variable "nControlID" to the contents of the table "tProperties".

Example 2

-- Specify which edit field control will be used for name
nNameEditField = CTRL_EDIT_01;

-- disable the edit field control
DlgEditField.SetProperties(nNameEditField, {Enabled = false});

-- prompt the user for first and last name
sName = Dialog.Input("User Input Required", "Please enter your first and last names:", "", MB_ICONQUESTION);

-- if the user presses cancel, set name to unknown
if sName == "Cancel" then
sName = "Unknown";
end

-- insert name string into edit field control
DlgEditField.SetProperties(nNameEditField, {Text = sName});

Disables the edit field control contained in the variable "nNameEditField", preventing the user from changing the field text. An input dialog is displayed requesting the user's first and last name. The results from this dialog are stored in the '01' edit field control.


DlgGroupBox.GetProperties Examples

DlgGroupBox.GetProperties

table DlgGroupBox.GetProperties (

number ControlID )

Example 1

tbGroupBox = DlgGroupBox.GetProperties(CTRL_GROUP_BOX_01);

Gets the properties for the group box control and stores them in table "tbGroupBox."


DlgGroupBox.SetProperties Examples

DlgGroupBox.SetProperties

DlgGroupBox.SetProperties (

number ControlID,

table Properties )

Example 1

tbProperties = {Text="My Group Box"};
DlgGroupBox.SetProperties(CTRL_GROUP_BOX_01, tbProperties);

Sets the group box control CTRL_GROUP_BOX1's text to "My Group Box."


DlgListBox.AddItem Examples

DlgListBox.AddItem

number DlgListBox.AddItem (

number ControlID,

string Text )

Example 1

index = DlgListBox.AddItem(CTRL_LIST_BOX, "Add me!! NOW!!!");

Adds an item with text "Insert me!! NOW!!!" into the list box control with control id "CTRL_LIST_BOX."

Example 2

index = DlgListBox.AddItem(nControlID, InsertText);

Adds an item with text stored in the variable "InsertText" into the list box control whose control ID is stored in the variable "nControlID."

Example 3

DlgListBox.SetUpdate(nControlID, false);

for count = 1, 10 do
index = DlgListBox.AddItem(nControlID, "Added Item " .. count);
end

DlgListBox.SetUpdate(nControlID, true);

This example disables updating of the list box control whose control id is stored in the variable "nControlID," adds ten items, and enables updating.


DlgListBox.DeleteItem Examples

DlgListBox.DeleteItem

number DlgListBox.DeleteItem (

number ControlID,

number Index )

Example 1

LastSelected = DlgListBox.DeleteItem(CTRL_LIST_BOX, 3);

Removes the third item from the list box control with control id CTRL_LIST_BOX and stores the last selected line number in the variable LastSelected.

Example 2

DlgListBox.DeleteItem(ControlID, -1);

Removes all items from the list box control whose ID is specified in the variable ControlID.

Note: Even though no return variable is specified, this action still functions correctly.


DlgListBox.FindItem Examples

DlgListBox.FindItem

number DlgListBox.FindItem (

number ControlID,

number StartAfter,

string SearchText )

Example 1

Position = DlgListBox.FindItem(CTRL_LIST_BOX, -1, "Location*");

Searches the entire list box control for any item starting with "Location" and stores the first found location in the variable "Position."

Example 2

--Initialize all variables used
continue = true;
search_start = 1;
all_locations = {};

--Keep searching listbox until told not to
while continue do
-- search listbox starting at position search_start
location = DlgListBox.FindItem(CTRL_LIST_BOX, search_start, "*winner*");
-- if search fails or nothing is found, do not continue
if location == -1 then
continue = false;
else
-- set next search start position, insert found value in table
search_start = location + 1;
Table.Insert(all_locations, Table.Count(all_locations) + 1, location);
end
end

This example searches the entire list box control for any items which contain "winner" and stores all of their locations in the table "all_locations."


DlgListBox.GetCount Examples

DlgListBox.GetCount

number DlgListBox.GetCount (

number ControlID )

Example 1

result = DlgListBox.GetCount(CTRL_LIST_BOX);

Gets the number of items in the list box control and stores it in the variable "result."


DlgListBox.GetItemProperties Examples

DlgListBox.GetItemProperties

table DlgListBox.GetItemProperties (

number ControlID,

number Index )

Example 1

tProps = DlgListBox.GetItemProperties(CTRL_LIST_BOX, 3);

Gets the properties from the third item in the list box control with control ID "CTRL_LIST_BOX" and stores it in the table "tProps."

Example 2

properties = DlgListBox.GetItemProperties(ControlID, -1);

Gets the properties from the last item in the list box control whose control ID is stored in "ControlID" and stores it in the table "properties."


DlgListBox.GetProperties Examples

DlgListBox.GetProperties

table DlgListBox.GetProperties (

number ControlID )

Example 1

tbProperties = DlgListBox.GetProperties(CTRL_LIST_BOX);

Gets the properties of the list box control with control id "CTRL_LIST_BOX" and stores them in the table "tbProperties."

Example 2

tbProps = DlgListBox.GetProperties(nControlID);

Gets the properties of the list box control whose id is stored in the variable "nControlID" and stores them in the table "tbProps."


DlgListBox.GetSelected Examples

DlgListBox.GetSelected

table DlgListBox.GetSelected (

number ControlID )

Example 1

tSelected = DlgListBox.GetSelected(CTRL_LIST_BOX);

Gets the indexes of all selected items in the list box control with control id "CTRL_LIST_BOX" and stores them in the table "tSelected."

Example 2

Selected_Items_Index = DlgListBox.GetSelected(nControlID);

Gets the indexes of all selected items in the list box control whose control id is stored in the variable "nControlID" and stores them in the table "Selected_Items_Index."


DlgListBox.GetSelectedCount Examples

DlgListBox.GetSelectedCount

number DlgListBox.GetSelectedCount (

number ControlID )

Example 1

number_selected = DlgListBox.GetSelectedCount(CTRL_LIST_BOX);

Gets the number of selected items from the list box control with control id "CTRL_LIST_BOX" and stores it in the variable "number_selected."

Example 2

selected_items = DlgListBox.GetSelectedCount(nControlID);

Gets the number of selected items from the list box whose control id is stored in the variable "nControlID" and stores it in the variable "selected_items."


DlgListBox.InsertItem Examples

DlgListBox.InsertItem

number DlgListBox.InsertItem (

number ControlID,

number Index,

string Text )

Example 1

index = DlgListBox.InsertItem(CTRL_LIST_BOX, 4, "Insert me!! NOW!!!");

Inserts an item with text "Insert me!! NOW!!!" into the 4th position of the list box control with control id "CTRL_LIST_BOX."

Example 2

inserted_location = DlgListBox.InsertItem(nControlID, -1, InsertText);

Inserts an item with the text stored in the variable "InsertText" into the last position of the list box control whose control ID is stored in the variable "nControlID."

Example 3

DlgListBox.SetUpdate(nControlID, false);

for count = 1, 10 do
item_number = DlgListBox.InsertItem(nControlID, -1, "Inserted Item " .. count);
end

DlgListBox.SetUpdate(nControlID, true);

This example disables updating of the list box control whose control id is stored in the variable "nControlID", inserts ten items at the end of the control, and enables updating.


DlgListBox.SetItemProperties Examples

DlgListBox.SetItemProperties

DlgListBox.SetItemProperties (

number ControlID,

number Index,

table Properties )

Example 1

DlgListBox.SetItemProperties(CTRL_LIST_BOX, 4, {Checked=true, Selected=true});

Sets the 4th item in the list box control with control id "CTRL_LIST_BOX" to checked and selected.

Example 2

DlgListBox.SetItemProperties(nControlID, nLocation, tbProps);

Sets the properties of the item with location stored in the variable "nLocation" to the properties stored in the table "tbProps". This applies to the list box control whose control ID is stored in the variable "nControlID."


DlgListBox.SetProperties Examples

DlgListBox.SetProperties

DlgListBox.SetProperties (

number ControlID,

table Properties )

Example 1

DlgListBox.SetProperties(CTRL_LIST_BOX, {Enabled=false});

Disables the list box control with control id "CTRL_LIST_BOX."

Example 2

DlgListBox.SetProperties(CTRL_LIST_BOX, {Visible=false});

Sets the visibility of the list box control with control id "CTRL_LIST_BOX" to false.

Example 3

DlgListBox.SetItemProperties(nControlID, tbProperties);

Sets the properties of the list box whose control is stored in the variable "nControlID" to the properties contained in the table "tbPproperties".


DlgListBox.SetUpdate Examples

DlgListBox.SetUpdate

DlgListBox.SetUpdate (

number ControlID,

boolean Update = true )

Example 1

DlgListBox.SetUpdate(CTRL_LIST_BOX, false);

Sets the list box control with control id "CTRL_LIST_BOX" to not update.

Example 2

DlgListBox.SetUpdate(CTRL_LIST_BOX, true);

Sets the list box control with control id "CTRL_LIST_BOX" to update.

Example 3

DlgListBox.SetUpdate(nControlID, false);

for count = 1, 10 do
DlgListBox.InsertItem(nControlID, -1, "Inserted Item " .. count);
end

DlgListBox.SetUpdate(nControlID, true);

This example disables updating of the list box control whose control id is stored in the variable "nControlID", adds ten items, and enables updating.


DlgProgressBar.GetPos Examples

DlgProgressBar.GetPos

number DlgProgressBar.GetPos (

number ControlID )

Example 1

nPos = DlgProgressBar.GetPos(CTRL_PROGRESS_BAR_01);

Gets the current position of the '01' progress control and stores it in "nPos".

Example 2

position = DlgProgressBar.GetPos(Progress_Control);
err = Application.GetLastError();

if (err ~= 0) then
Dialog.Message("Error #" .. err, _tblErrorMessages[err]);
end

Gets the current position of the progress control referenced in variable "Progress_Control" and stores it in "position." If an error occurred, a dialog is displayed.


DlgProgressBar.GetProperties Examples

DlgProgressBar.GetProperties

table DlgProgressBar.GetProperties (

number ControlID )

Example 1

props = DlgProgressBar.GetProperties(CTRL_PROGRESS_BAR_02);

Gets the properties from the 2nd progress bar control and stores them in the table "props".

Example 2

-- function ToString () converts a boolean value (true/false)
-- to a string (True, False). If the value passed is not
-- of type boolean, the passed value is returned unchanged.
function ToString(Value)
-- Ensure value is type boolean
if type (Value) ~= "boolean" then
-- Value is not type boolean, return unchanged
return Value;
elseif Value then
-- Value is true, return string True
return "True";
else
-- Value is false, return string False
return "False";
end
end

-- Retrieve the properties from progress bar control 01
tProperties = DlgProgressBar.GetProperties(CTRL_PROGRESS_BAR_01);

-- Show the Debug Window.
Debug.ShowWindow(true);

-- For each property in the table, do this
for Property, Value in pairs(tProperties) do
-- Output property to debug window
Debug.Print(Property .. ": " .. ToString(Value) .. "\r\n\r\n");
end

Gets the properties of the '01' progress bar control and outputs them to the debug window. The function ToString is used to convert any boolean values to strings. If the function is passed a value that is not boolean, the value is returned unchanged.


DlgProgressBar.GetRange Examples

DlgProgressBar.GetRange

table DlgProgressBar.GetRange (

number ControlID )

Example 1

range = DlgProgressBar.GetRange(CTRL_PROGRESS_BAR_01);

Gets the range of the '01' progress bar control and stores it in the table "tRange".

Example 2

tRange = DlgProgressBar.GetRange(CTRL_PROGRESS_BAR_02);

nNumberOfSteps = tRange.End - tRange.Begin;

Dialog.Message("Progress Bar Fact:", "This progress bar contains " .. nNumberOfSteps .. " steps!");

Gets the range of the '02' progress bar control and stores it in the table "tRange". The number of steps in this control is calculated and displayed to the user.

Example 3

-- Get the range and position of the progress bar control
tRange = DlgProgressBar.GetRange(CTRL_PROGRESS_BAR_01);

nPos = DlgProgressBar.GetPos(CTRL_PROGRESS_BAR_01);

-- Calculate the percent complete
nPercent = (nPos - tRange.Begin) / (tRange.End - tRange.Begin);

Gets the range and current position of the '01' progress bar control. The percent complete is calculated and stored in the variable "nPercent" as a decimal value (e.g. 0.473).


DlgProgressBar.SetPos Examples

DlgProgressBar.SetPos

DlgProgressBar.SetPos (

number ControlID,

number Pos )

Example 1

position = DlgProgressBar.SetPos(nControlID, nPos);

Sets the position of the progress bar control in "nControlID" to the value in the variable "nPos".

Example 2

-- Get the range progress bar control
tRange = DlgProgressBar.GetRange(CTRL_PROGRESS_BAR_01);

-- If the user-defined process is complete, set the control's position to 'end'.
if bProcessComplete then
DlgProgressBar.SetPos(CTRL_PROGRESS_BAR_01, tRange.End);
end

Gets the range for the '01' progress bar control and stores it in the table "tRange". If the boolean variable "bProcessComplete" is set to true, the position of the control is set to the greatest possible value.


DlgProgressBar.SetProperties Examples

DlgProgressBar.SetProperties

DlgProgressBar.SetProperties (

number ControlID,

table Properties )

Example 1

DlgProgressBar.SetProperties(CTRL_PROGRESS_BAR_01, {Visible = false, Enabled = false});

Disables and hides the '01' progress bar control on the current screen.

Example 2

tProperties = DlgProgressBar.GetProperties(nControlID);

if not tProperties.Visible then
tProperties.Visible = true;
DlgProgressBar.SetProperties(nControlID, tProperties);
end

Gets the properties of the progress bar control whose id is stored in nControlID. If this control is not visible, it is made visible.


DlgProgressBar.SetRange Examples

DlgProgressBar.SetRange

DlgProgressBar.SetRange (

number ControlID,

number Begin,

number End )

Example 1

DlgProgressBar.SetRange(CTRL_PROGRESS_BAR_02, 0, 1000);

Sets the range of the '02' progress bar from 0 to 1000.

Example 2

nNumberFiles = 307;

DlgProgressBar.SetRange(CTRL_PROGRESS_BAR_01, 0, nNumberFiles);

Sets the range of the '01' progress bar control from 0 to the number of files that you specify.


DlgProgressBar.SetStep Examples

DlgProgressBar.SetStep

DlgProgressBar.SetStep (

number ControlID,

number Step )

Example 1

DlgProgressBar.SetStep(CTRL_PROGRESS_BAR_01, 10);

Sets the increment size of the '01' progress bar control to 10.

Example 2

DlgProgressBar.SetStep(nControlID, nStep);

Sets the increment size of the progress bar control referenced in "nControlID" to the value in "nStep".


DlgProgressBar.Step Examples

DlgProgressBar.Step

DlgProgressBar.Step (

number ControlID )

Example 1

DlgProgressBar.Step(CTRL_PROGRESS_BAR_01);

Increments the '01' progress bar control one step.


DlgRadioButton.GetProperties Examples

DlgRadioButton.GetProperties

table DlgRadioButton.GetProperties (

number ControlID )

Example 1

props = DlgRadioButton.GetProperties(CTRL_RADIO_BUTTON_03);

Gets the properties from the 3rd radio button and stores them in the table "props".

Example 2

-- function ToString () converts a boolean value (true/false)
-- to a string (True, False). If the value passed is not
-- of type boolean, the passed value is returned unchanged.
function ToString(Value)
-- Ensure value is type boolean
if type (Value) ~= "boolean" then
-- Value is not type boolean, return unchanged
return Value;
elseif Value then
-- Value is true, return string True
return "True";
else
-- Value is false, return string False
return "False";
end
end

-- Retrieve the properties from radio button control 01
tProperties = DlgRadioButton.GetProperties(CTRL_RADIO_BUTTON_01);

-- Show the Debug Window.
Debug.ShowWindow(true);

-- For each property in the table, do this
for Property, Value in pairs(tProperties) do
-- Output property to debug window
Debug.Print(Property .. ": " .. ToString(Value) .. "\r\n\r\n");
end

Gets the properties of the '01' radio button control and outputs them to the debug window. The function ToString is used to convert any boolean values to strings. If the function is passed a value that is not boolean, the value is returned unchanged.


DlgRadioButton.SetProperties Examples

DlgRadioButton.SetProperties

DlgRadioButton.SetProperties (

number ControlID,

table Properties )

Example 1

DlgRadioButton.SetProperties(CTRL_RADIO_BUTTON_01, tProperties);

Sets the properties of the '01' radio button to those contained in the table called "tProperties."

Example 2

DlgRadioButton.SetProperties(CTRL_RADIO_BUTTON_02, {Visible = false, Enabled = false});

Disables and hides the '02' radio button on the current screen.

Example 3

tRButtonProperties = DlgRadioButton.GetProperties(nControlID);

if not tRButtonProperties.Visible then
tRButtonProperties.Visible = true;
DlgButton.SetProperties(nControlID, tRButtonProperties);
end

Gets the properties of the radio button whose id is stored in nControlID. If this radio button is currently not visible, it is made visible using the DlgRadioButton.SetProperties action.


DlgScrollingText.AppendLine Examples

DlgScrollingText.AppendLine

DlgScrollingText.AppendLine (

number ControlID,

string Line = "",

boolean AddNewLine = true,

boolean ScrollToEnd = true )

Example 1

DlgScrollingText.AppendLine(CTRL_SCROLLTEXT_BODY, "I agree to the above terms.", true, false);

Appends the text "I agree to the above terms" to the end of the scrolling text control.

Example 2

DlgScrollingText.AppendLine(nControlID, sLineToAdd, true, true);

Appends the text stored in string 'sLineToAdd' to the end of the scrolling text control referenced in the variable 'nControlID'. The control is set to scroll to the bottom once the new text is appended.


DlgScrollingText.GetProperties Examples

DlgScrollingText.GetProperties

table DlgScrollingText.GetProperties (

number ControlID )

Example 1

props = DlgScrollingText.GetProperties(CTRL_SCROLLTEXT_BODY);

Gets the properties from the "body" scrolling text control and stores them in the table "props".

Example 2

-- function ToString () converts a boolean value (true/false)
-- to a string (True, False). If the value passed is not
-- of type boolean, the passed value is returned unchanged.
function ToString(Value)
-- Ensure value is type boolean
if type (Value) ~= "boolean" then
-- Value is not type boolean, return unchanged
return Value;
elseif Value then
-- Value is true, return string True
return "True";
else
-- Value is false, return string False
return "False";
end
end

-- Retrieve the properties from scrolling text control 'body'
tProperties = DlgScrollingText.GetProperties(CTRL_SCROLLTEXT_BODY);

-- Show the Debug Window.
Debug.ShowWindow(true);

-- For each property in the table, do this
for Property, Value in pairs(tProperties) do
-- Output property to debug window
Debug.Print(Property .. ": " .. ToString(Value) .. "\r\n\r\n");
end

Gets the properties of the "body" scrolling text control and outputs them to the debug window. The function ToString is used to convert any boolean values to strings. If the function is passed a value that is not boolean, the value is returned unchanged.


DlgScrollingText.SetProperties Examples

DlgScrollingText.SetProperties

DlgScrollingText.SetProperties (

number ControlID,

table Properties )

Example 1

DlgScrollingText.SetProperties(CTRL_SCROLLTEXT_BODY, {Visible = false, Enabled = false});

Disables and hides the "body" scrolling text control on the current screen.

Example 2

tProperties = DlgScrollingText.GetProperties(nControlID);

if not tProperties.Visible then
tProperties.Visible = true;
DlgScrollingText.SetProperties(nControlID, tProperties);
end

Gets the properties of the scrolling text control whose id is stored in nControlID. If this control is not visible, it is made visible.


DlgSelectPackages.GetCategoryProperties Examples

DlgSelectPackages.GetCategoryProperties

table DlgSelectPackages.GetCategoryProperties (

number PackageControlID,

number CategoryControlID )

Example 1

tbProperties = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002);

Gets the properties of the second package category in the packages control.

Example 2

-- Get the properties of the first category
tProps = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001);

-- If it was expanded, collapse it, otherwise expand it
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {Expanded = not tProps.Expanded});

-- Update the display
DlgSelectPackages.UpdateDisplay(CTRL_SELECT_PACKAGE_TREE);

This example toggles the expanded state of a package category.

Example 3

if(e_CtrlID == CTRL_SELECT_PACKAGE_TREE) then
-- the control message is from the select packages tree...
-- if an item's state changed (i.e. a package was turned on or off),
if(e_MsgID == MSGID_ONSTATECHANGED) and (e_Details.nCtrlID == CTRL_CATEGORY_001 or e_Details.nCtrlID == CTRL_CATEGORY_002) then
-- an item's state has changed, and the item is either the first or the second package category
if e_Details.nCtrlID == CTRL_CATEGORY_001 then
-- the first package category's state changed
tProps = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001);
if tProps.State > 1 then
-- state is indeterminate or unchecked. Set state to unchecked, set other category's state to checked
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=2});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=1});
else
-- is checked, uncheck other one
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=1});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=2});
end
elseif e_Details.nCtrlID == CTRL_CATEGORY_002 then
-- the second package category's state changed
tProps = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001);
if tProps.State > 1 then
-- state is indeterminate or unchecked. set state to unchecked, set other category's state to checked
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=2});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=1});
else
-- is checked, uncheck other one
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=1});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=2});
end
end
-- update the package display
DlgSelectPackages.UpdateDisplay(CTRL_SELECT_PACKAGE_TREE);
end
end

In a packages control with two categories, if the first category is checked, the second will be unchecked. If the first is unchecked, the second will be checked. This action script is meant to be located on the On Ctrl Message event.

Note: Please note that this example does not take into account categories which are indeterminate. The first two categories will either be set to checked, or unchecked.


DlgSelectPackages.SetCategoryProperties Examples

DlgSelectPackages.SetCategoryProperties

DlgSelectPackages.SetCategoryProperties (

number PackageControlID,

number CategoryControlID,

table Properties )

Example 1

DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_003, {Enabled=false});

Disables the third package category in the packages control.

Example 2

-- Get the properties of the first category
tProps = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001);

-- If it was expanded, collapse it, otherwise expand it
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {Expanded = not tProps.Expanded});

-- Update the display
DlgSelectPackages.UpdateDisplay(CTRL_SELECT_PACKAGE_TREE);

This example toggles the expanded state of a package category.

Example 3

if(e_CtrlID == CTRL_SELECT_PACKAGE_TREE) then
-- the control message is from the select packages tree...
-- if an item's state changed (i.e. a package was turned on or off),
if(e_MsgID == MSGID_ONSTATECHANGED) and (e_Details.nCtrlID == CTRL_CATEGORY_001 or e_Details.nCtrlID == CTRL_CATEGORY_002) then
-- an item's state has changed, and the item is either the first or the second package category
if e_Details.nCtrlID == CTRL_CATEGORY_001 then
-- the first package category's state changed
tProps = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001);
if tProps.State > 1 then
-- state is indeterminate or unchecked. Set state to unchecked, set other category's state to checked
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=2});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=1});
else
-- is checked, uncheck other one
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=1});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=2});
end
elseif e_Details.nCtrlID == CTRL_CATEGORY_002 then
-- the second package category's state changed
tProps = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001);
if tProps.State > 1 then
-- state is indeterminate or unchecked. set state to unchecked, set other category's state to checked
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=2});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=1});
else
-- is checked, uncheck other one
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=1});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=2});
end
end
-- update the package display
DlgSelectPackages.UpdateDisplay(CTRL_SELECT_PACKAGE_TREE);
end
end

In a packages control with two categories, if the first category is checked, the second will be unchecked. If the first is unchecked, the second will be checked. This action script is meant to be located on the On Ctrl Message event.

Note: Please note that this example does not take into account categories which are indeterminate. The first two categories will either be set to checked, or unchecked.


DlgSelectPackages.UpdateDisplay Examples

DlgSelectPackages.UpdateDisplay

DlgSelectPackages.UpdateDisplay (

number ControlID )

Example 1

DlgSelectPackages.UpdateDisplay(CTRL_SELECT_PACKAGE_TREE);

Updates the packages control.

Example 2

-- Get the properties of the first catagory
tProps = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001);

-- If it was expanded, collapse it, otherwise expand it
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {Expanded = not tProps.Expanded});

-- Update the display
DlgSelectPackages.UpdateDisplay(CTRL_SELECT_PACKAGE_TREE);

This example toggles the expanded state of a package category.

Example 3

if(e_CtrlID == CTRL_SELECT_PACKAGE_TREE) then
-- the control message is from the select packages tree...
-- if an item's state changed (i.e. a package was turned on or off),
if(e_MsgID == MSGID_ONSTATECHANGED) and (e_Details.nCtrlID == CTRL_CATEGORY_001 or e_Details.nCtrlID == CTRL_CATEGORY_002) then
-- an item's state has changed, and the item is either the first or the second package category
if e_Details.nCtrlID == CTRL_CATEGORY_001 then
-- the first package category's state changed
tProps = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001);
if tProps.State > 1 then
-- state is indeterminate or unchecked. Set state to unchecked, set other category's state to checked
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=2});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=1});
else
-- is checked, uncheck other one
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=1});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=2});
end
elseif e_Details.nCtrlID == CTRL_CATEGORY_002 then
-- the second package category's state changed
tProps = DlgSelectPackages.GetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001);
if tProps.State > 1 then
-- state is indeterminate or unchecked. set state to unchecked, set other category's state to checked
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=2});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=1});
else
-- is checked, uncheck other one
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_002, {State=1});
DlgSelectPackages.SetCategoryProperties(CTRL_SELECT_PACKAGE_TREE, CTRL_CATEGORY_001, {State=2});
end
end
-- update the package display
DlgSelectPackages.UpdateDisplay(CTRL_SELECT_PACKAGE_TREE);
end
end

In a packages control with two categories, if the first category is checked, the second will be unchecked. If the first is unchecked, the second will be checked. This action script is meant to be located on the On Ctrl Message event.

Note: Please note that this example does not take into account categories which are indeterminate. The first two categories will either be set to checked, or unchecked.


DlgStaticText.GetProperties Examples

DlgStaticText.GetProperties

table DlgStaticText.GetProperties (

number ControlID )

Example 1

tST_Prop = DlgStaticText.GetProperties(CTRL_STATICTEXT_BODY);

Gets the properties from the 'body' static text control and stores them in the table "tST_Prop".

Example 2

-- function ToString () converts a boolean value (true/false)
-- to a string (True, False). If the value passed is not
-- of type boolean, the passed value is returned unchanged.
function ToString(Value)
-- Ensure value is type boolean
if type (Value) ~= "boolean" then
-- Value is not type boolean, return unchanged
return Value;
elseif Value then
-- Value is true, return string True
return "True";
else
-- Value is false, return string False
return "False";
end
end

-- Retrieve the properties from Static Text control
tProperties = DlgStaticText.GetProperties(CTRL_STATICTEXT_BODY);

-- Show the Debug Window.
Debug.ShowWindow(true);

-- For each property in the table, do this
for Property, Value in pairs(tProperties) do
-- Output property to debug window
Debug.Print(Property .. ": " .. ToString(Value) .. "\r\n\r\n");
end

Gets the properties of the 'body' static text control and outputs it to the debug window. The function ToString is used to convert any boolean values to strings. If the function is passed a value that is not boolean, the value is returned unchanged.


DlgStaticText.SetProperties Examples

DlgStaticText.SetProperties

DlgStaticText.SetProperties (

number ControlID,

table Properties )

Example 1

DlgStaticText.SetProperties(CTRL_STATICTEXT_BODY, {Visible = false});

Hides the 'body' static text control on the current screen.

Example 2

tProperties = DlgStaticText.GetProperties(nControlID);

if not tProperties.Visible then
tProperties.Visible = true;
DlgStaticText.SetProperties(nControlID, tProperties);
end

Gets the properties of the static text control whose id is stored in nControlID. If this control is not visible, it is made visible.


DLL.CallFunction Examples

DLL.CallFunction

string DLL.CallFunction (

string Filename,

string FunctionName,

string Parameters = "",

number ReturnType = 0,

number CallConvention = 0 )

Example 1

DLLResult = DLL.CallFunction("winmm.dll", "mciSendStringA", "\"Set CDAudio Door Open\",0,0,0", DLL_RETURN_TYPE_LONG, DLL_CALL_STDCALL);

Calls the mciSendStringA function in the Windows winmm.dll file to send a "Set CD Audio Door Open" command to the MCI driver (along with two parameters, both 0). This causes the CD-ROM drive tray to open (i.e. it ejects the CD).

Example 2

DLL.CallFunction ( _SystemFolder .. "\\User32.dll", "SetCursorPos", "0,0", DLL_RETURN_TYPE_LONG, DLL_CALL_STDCALL);

Calls the SetCursorPos function in the "Windows\System32\User32.dll" file to move the mouse cursor to the upper left corner of the screen (i.e. to coordinates "0,0"). Since no variable is provided to store the return value, if the DLL function returns anything it will just be ignored.


Drive.Eject Examples

Drive.Eject

Drive.Eject (

string Drive )

Example 1

Drive.Eject(_SourceDrive);

Ejects the CD/DVD-ROM drive the installation is currently running from.

Note: _SourceDrive is a built-in variable that contains the drive letter where the setup.exe file is located.

Example 2

Drive.Eject(_SourceFolder);

Ejects the CD/DVD-ROM drive the installation is currently running from.

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 3

-- Eject the current drive.
Drive.Eject(_SourceFolder);

-- Determine if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Ejects the CD/DVD-ROM drive the installation is currently running from. If an error occurs, the error code message is shown in a dialog message.

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 4

-- Get the type of the drive where the installation is running from.
drive_type = Drive.GetType(_SourceDrive);

-- If the drive type is a CD/DVD ROM drive, eject it.
if (drive_type == DRIVE_CDROM) then
Drive.Eject(_SourceDrive);
end

Determines what type of drive the installation is run from and stores the result in drive_type. If the user is running it from a CD-ROM or DVD-ROM drive the drive would be ejected.

Note: _SourceDrive is a built-in variable that contains the drive letter where the setup.exe file is located.


Drive.Enumerate Examples

Drive.Enumerate

table Drive.Enumerate (

)

Example 1

Drives = Drive.Enumerate();

Gets all of the drive letters on the user's system and stores them in a numerically indexed table of drive letters. Drives[1] will likely have a value such as A:\ and Drives[2] will likely have a value such as C:\.

Example 2

-- Get a list of the available drives.
drives = Drive.Enumerate();

-- Determine if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
-- If no error occurred, display the available drives in a dialog.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else

-- Create a string consisting of all of the drive letters and display them.
all_drives = Table.Concat(drives, "\r\n");
Dialog.Message("Notice", "Below is a list of all of your current drives:\r\n"..all_drives);
end

Gets all of the drive letters on the user's system and stores them in a numerically indexed table of drive letters called "drives". If an error occurs, the error code message is displayed. If no error occurs, a dialog message is shown listing all of the current drives.


Drive.GetFreeSpace Examples

Drive.GetFreeSpace

number Drive.GetFreeSpace (

string Drive )

Example 1

Free_Space = Drive.GetFreeSpace("C:\\");

Gets the free disk space on the user's "C:\" drive and stores the result in a variable called "Free_Space."

Example 2

how_big = Drive.GetFreeSpace(Read_Drive);

Takes the variable "Read_Drive" that contains a path with a drive letter and stores the free disk space value in how_big.

Example 3

--space required, in megabytes
space_required = 253

--get free space on the user's system (c:\ drive)
space_available = Drive.GetFreeSpace("C:");

-- Determine if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else

--compare free space available to free space required
if space_required > space_available then
Dialog.Message("","You are "..(space_required - space_available).." MB short");
else
Dialog.Message("","You have "..(space_available - space_required).." MB more than you need");
end
end

Determines if the user has enough free space on their system given a space requirement.

Note: The variable space_required must be set by you. 253 is an arbitrary number.


Drive.GetInformation Examples

Drive.GetInformation

table Drive.GetInformation (

string Drive )

Example 1

tDriveInfo = Drive.GetInformation("C:\\");

Gets the drive information from the 'C:' drive, and stores it in the table "tDriveInfo".

Example 2

-- Set this value to the expected serial number of the
-- drive that your setup will run from.
Expected_Serial = 123456789;

-- Gets the source drive's current serial number
Current_Serial = Drive.GetInformation(_SourceDrive).SerialNumber;

-- Compares the two serials and, if different, terminates the app.
if (Current_Serial ~= Expected_Serial) then
Dialog.Message("ERROR", "This is an unauthorized copy of the original installer, and will shut down.", MB_OK, MB_ICONSTOP);
Application.Exit();
end

Gets the source drive's serial number and compares it to the 'expected' serial number. If they don't match, the install is terminated.


Drive.GetSize Examples

Drive.GetSize

number Drive.GetSize (

string Drive )

Example 1

drive_size = Drive.GetSize("C:\\");

Gets the size of the user's "C:\" drive and stores the result in a variable called "drive_size."

Example 2

how_big = Drive.GetSize(His_Drive);

Takes the variable "His_Drive" that contains a path with a drive letter and stores the drive's size in how_big.

Example 3

--Specify which drive will be checked
sDrive = "C:";

--Get total size of user's C drive:
nTotalSize = Drive.GetSize(sDrive);

-- Determine if an error occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
--Get the used space
nUsedSpace = Drive.GetUsedSpace(sDrive);
-- Determine if an error occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
-- Calculate the drive percentage used, and round up
nPercentageUsed = (nUsedSpace / nTotalSize) * 100;
nPercentageUsed = Math.Ceil(nPercentageUsed);

-- Output percentage to the user
Dialog.Message("","Your drive is "..nPercentageUsed.."% full.");
end
end

This example determines what percentage of the user's C: drive is currently full of data.


Drive.GetType Examples

Drive.GetType

number Drive.GetType (

string Drive )

Example 1

drive_type = Drive.GetType("C:\\");

Gets the type of drive given the drive letter "C:\" and stores the numeric result in a variable called "drive_type." Normally a value of 3 would be returned meaning their "C:" drive is a fixed drive.

Example 2

what_type = Drive.GetType(_SourceDrive);

Determines what type of drive the installer is run from and stores the result in what_type. If the user was running it from a CD-ROM or DVD-ROM drive, the variable what_type would contain the value 5.

Note: _SourceDrive is a built-in variable that contains the drive letter where the setup.exe file is located.

Example 3

-- Get the type of the drive where the installer is running from.
drive_type = Drive.GetType(_SourceDrive);

-- If the drive type is a CD/DVD ROM drive, eject it.
if (drive_type == DRIVE_CDROM) then
Drive.Eject(_SourceDrive);
end

Determines what type of drive the installation is run from and stores the result in drive_type. If the user is running it from a CD-ROM or DVD-ROM drive the drive would be ejected.

Note: _SourceDrive is a built-in variable that contains the drive letter where the setup.exe file is located.


Drive.GetUsedSpace Examples

Drive.GetUsedSpace

number Drive.GetUsedSpace (

string Drive )

Example 1

Used_Space = Drive.GetUsedSpace("C:\\");

Gets the used disk space on the user's "C:\" drive and stores the result in a variable called "Used_Space."

Example 2

how_much = Drive.GetUsedSpace(Read_Drive);

Takes the variable "Read_Drive" that contains a path with a drive letter and stores the used disk space value in how_much.

Example 3

--Specify which drive will be checked
sDrive = "C:";

--Get total size of user's C drive:
nTotalSize = Drive.GetSize(sDrive);

-- Determine if an error occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
--Get the used space
nUsedSpace = Drive.GetUsedSpace(sDrive);
-- Determine if an error occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
-- Calculate the drive percentage used, and round up
nPercentageUsed = (nUsedSpace / nTotalSize) * 100;
nPercentageUsed = Math.Ceil(nPercentageUsed);

-- Output percentage to the user
Dialog.Message("","Your drive is "..nPercentageUsed.."% full.");
end
end

This example determines what percentage of the user's C: drive is currently full of data.


File.Copy Examples

File.Copy

File.Copy (

string Source,

string Destination,

boolean Recurse = true,

boolean Overwrite = true,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Example 1

File.Copy(_SourceFolder.."\\*.txt", _TempFolder .. "\\Text Files", false);

Copies all of the text files from the source folder (_SourceFolder) into a subfolder called "Text Files" inside the user's temp folder, and does not go into any subfolders inside the source folder as it searches for files ending in .txt.

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 2

File.Copy(_SourceFolder .. "\\hidden.dat", _TempFolder .. "\\z3j2rlk\\sneaky.exe", false, true, false, true, CB_Copy);

Copies a file named "hidden.dat" from the folder where the setup.exe is located to a folder named "z3j2rlk" in the user's temp folder, renaming the file to "sneaky.exe" in the process. The recurse option is turned off, and the other boolean parameters are set to their default values. A function named CB_Copy will be called whenever progress is made in the copy operation (i.e. every time x number of bytes are copied).

Example 3

-- Get the path to the user's My Documents folder.
DestFolder = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Create a folder in the user's My Documents folder called "Copied Files".
Folder.Create(DestFolder.."\\Copied Files");

--Copy all files within the Docs folder in the source folder to the destination.
StatusDlg.Show(MB_ICONNONE, false);
File.Copy(_SourceFolder.."\\Docs\\*.*", DestFolder.."\\Copied Files\\", true, true, false, true, nil);

-- Check to see if the File.Copy action failed by getting it's error code.
error = Application.GetLastError();
StatusDlg.Hide();

-- If it failed (not equal to 0), display a dialog informing the user.
-- If it succeeded, open an explore window showing the "Copied Files" folder.
if error ~= 0 then
result = Dialog.Message("Error", "There was an error copying the files to your system. Please try again.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
Shell.Execute(DestFolder.."\\Copied Files", "explore", "", "", SW_SHOWNORMAL);
end

Copies all files from the "Docs" folder in the source folder to a folder called "Copied Files" in the user's My Documents folder. If the operation fails, an error message is displayed. If the operation succeeds, the folder is opened in an explore window.


File.Delete Examples

File.Delete

File.Delete (

string Source,

boolean Recurse = false,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Example 1

File.Delete(_TempFolder.."\\TempSetup\\*.txt");

Deletes all of the text files in the "TempSetup" folder located in the user's Temporary folder, and does not go into any subfolders inside "TempSetup" as it searches for files ending in .txt.

Note: _TempFolder is a built-in variable that contains the path to the user's Temporary directory.

Example 2

File.Delete(_TempFolder .. "\\install.log", false, false, true, CB_Delete);

Deletes a file named "install.log" from the user's temp folder. The action is told not to recurse into subfolders, not to abort on failure, and to delete the file even if its "hidden" or "system" attributes are set. A function named CB_Delete will be called whenever progress is made in the delete operation (i.e. every time x number of bytes are deleted).

Example 3

-- Gets the path to the user's My Documents folder.
my_docs_path = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Check to see if the My Documents folder detection was successful.
if (Application.GetLastError() == 0)then

-- Search the user's My Documents folder for the file "Data.ini".
search_results = File.Find(my_docs_path, "Data.ini", true, false, nil);

--Check to see if an error occurred during the search. If it did, display the error message.
error = Application.GetLastError();
if error ~= 0 then
Dialog.Message("Error",_tblErrorMessages[error]);
else

-- If no files were found, notify the user.
if (search_results == nil) then
Dialog.Message("Notice", "Data.ini was not found in your My Documents folder.");

-- If files were found, display a dialog containing a list of their locations.
-- Also ask for deletion confirmation.
else
message = "Data.ini was found in the following location(s). Click OK to delete the file(s):\r\n\r\n";
for index, path in pairs(search_results) do
message = String.Concat(message, path.."\r\n");
end
proceed = Dialog.Message("File Search Results", message, MB_OKCANCEL, MB_ICONQUESTION, MB_DEFBUTTON1);

-- If the user clicked OK, delete all of the files found.
if proceed == IDOK then

-- Delete each file found in the search.
for index, path in pairs(search_results) do
File.Delete(path, false, false, false, nil);

-- Check to see if any errors occurred during the deletion.
if (Application.GetLastError() ~= 0) then
Dialog.Message("Error", "The file located at: "..path.." could not be deleted.");
end
end
end
end
end
end

This example uses the File.Find action to search for all copies of a particular INI file in the user's My Documents folder. If the file is found in more than one location, the user is presented with the list and asked if they wish to delete them. If they agree, each copy is deleted using the File.Delete action.


File.DeleteOnReboot Examples

File.DeleteOnReboot

File.DeleteOnReboot (

string Filename )

Example 1

File.DeleteOnReboot(_TempFolder.."\\DeleteMe.exe");

Removes the "DeleteMe.exe" file on the next system reboot.

Note: _TempFolder is a built-in variable that contains the path to the user's Temp directory.

Example 2

File.DeleteOnReboot("C:\\instructions.doc");

Deletes the file located at "C:\instructions.doc" on the next system reboot.


File.DoesExist Examples

File.DoesExist

boolean File.DoesExist (

string Filename )

Example 1

are_ya_there = File.DoesExist(_WindowsFolder.."\\targetfile.ini");

Stores true in a variable named "are_ya_there" if the "targetfile.ini" file exists in the user's Windows directory.

Note: _WindowsFolder is a built-in variable that contains the path to the user's Windows directory.

Example 2

-- Checks to see if a particular file exists.
are_ya_there = File.DoesExist(_WindowsFolder.."\\targetfile.ini");

-- If the file does not exist, display a message notifying the user.
if are_ya_there == false then
result = Dialog.Message("Notice", "The specified file does not exist.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end

Stores true in a variable named "are_ya_there" if the "targetfile.ini" file exists in the user's Windows directory. If the file does not exist, a dialog message is shown to the user.


File.ExploreFolder Examples

File.ExploreFolder

File.ExploreFolder (

string Path,

number WindowMode = SW_SHOWNORMAL )

Example 1

File.ExploreFolder("C:\\Documents and Settings", SW_MAXIMIZED);

Opens the "C:\Documents and Settings" folder in the Windows Explorer view, and maximizes the folder window.

Example 2

File.ExploreFolder("C:\\Temp");

Opens the "C:\Temp" folder in the Windows Explorer view.

Example 3

-- Get the path to the "My Documents" folder.
sMyDocumentsLocation = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Open an explore window to the "My Documents" folder
File.ExploreFolder(sMyDocumentsLocation, SW_MAXIMIZE);

Opens the user's "My Documents" folder in the Windows Explorer view, and maximizes the folder window.


File.Find Examples

File.Find

table File.Find (

string Folder,

string Filename,

boolean Recurse = false,

boolean IncludeFolders = false,

function CallbackFunction = nil,

function FileFoundCallbackFunction = nil )

Example 1

DLL_Files = File.Find(_SourceFolder, "*.dll", true, false, ShowSearchProgress, nil);

Searches for DLL files inside the folder that the installation is running from, and stores their paths in a table called DLL_Files. Since Recurse is true, the action will search inside subfolders. The function named ShowSearchProgress will be called whenever progress is made in the search operation. No callback function is used when a file is found.

Example 2

found = File.Find(Shell.GetFolder(SHF_MYDOCUMENTS), "*.pdf", true, false);
if (found) then
Dialog.Message("Found one!", "The first PDF file found was:" .. found[1]);
end

Searches for PDF files anywhere inside the user's My Documents folder, and stores the paths to any PDF files that are found in a table named "found." Then, the example tests that table to see if there were any files stored in it (if there weren't, it would have been set to nil by the File.Find action), and if there are, puts up a message dialog to show the path to the first PDF file that was found.

Example 3

directory_structure = File.Find(Shell.GetFolder(SHF_MYDOCUMENTS), "*.*", true, true);

Searches for all files inside of the user's My Documents folder. Since Recurse is true and IncludeFolders is true, the action will search inside subfolders and will return all files that were found as well as all folders that were encountered during the search.

Example 4

-- Gets the path to the user's My Documents folder.
my_docs_path = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Check to see if the My Documents folder detection was successful.
if (Application.GetLastError() == 0)then

-- Search the user's My Documents folder for the file "Data.ini".
search_results = File.Find(my_docs_path, "Data.ini", true, false, nil);

--Check to see if an error occurred during the search. If it did, display the error message.
error = Application.GetLastError();
if error ~= 0 then
Dialog.Message("Error",_tblErrorMessages[error]);
else

-- If no files were found, notify the user.
if (search_results == nil) then
Dialog.Message("Notice", "Data.ini was not found in your My Documents folder.");

-- If files were found, display a dialog containing a list of their locations.
-- Also ask for deletion confirmation.
else
message = "Data.ini was found in the following location(s). Click OK to delete the file(s):\r\n\r\n";
for index, path in pairs(search_results) do
message = String.Concat(message, path.."\r\n");
end
proceed = Dialog.Message("File Search Results", message, MB_OKCANCEL, MB_ICONQUESTION, MB_DEFBUTTON1);

-- If the user clicked OK, delete all of the files found.
if proceed == IDOK then

-- Delete each file found in the search.
for index, path in pairs(search_results) do
File.Delete(path, false, false, false, nil);

-- Check to see if any errors occurred during the deletion.
if (Application.GetLastError() ~= 0) then
Dialog.Message("Error", "The file located at: "..path.." could not be deleted.");
end
end
end
end
end
end

This example uses the File.Find action to search for all copies of a particular INI file in the user's My Documents folder. If the file is found in more than one location, the user is presented with the list and asked if they wish to delete them. If they agree, each copy is deleted using the File.Delete action.

Example 5

-- Callback function, used when a match is found
function found (filename)
-- Display a dialog to the user
Dialog.Message("FOUND!!", filename .. " was found!!\r\nNow terminating find . . .");
-- return false (end the find action)
return false;
end

-- Show the status dialog
StatusDlg.Show();

-- Find any filename containing 'win'. Call function 'found' whenever a match is found
File.Find("c:\\", "*win*.*", true, false, nil, found);

-- Hide the status dialog
StatusDlg.Hide();

This example searches the user's entire hard-drive for filenames containing 'win'. When a match is found, the function 'found' is called, and the search is terminated. Using the technique above, a File.Find action can be terminated as soon as one match is found, regardless of how many matches exist in the search location.

Example 6

g_FolderSize = 0;

-- This function determines the size of a file and adds it to the total.
-- This function is used as the callback function for the File.Find action in this example.
function OnFileFound(Path)
local nSize = File.GetSize(Path);
g_FolderSize = g_FolderSize + nSize;
return true;
end

-- Allow the user to browse for a folder whose size they want.
local strFolder = Dialog.FolderBrowse("Find a folder",Shell.GetFolder(SHF_MYDOCUMENTS));

StatusDlg.Show();
tblFiles = File.Find(strFolder,"*.*",true,false,nil,OnFileFound);
StatusDlg.Hide();
Dialog.Message("Size",String.GetFormattedSize(g_FolderSize));

This example calculates the total size of a selected folder's contents. To accomplish this, the File.Find action is called with the callback function called "OnFileFound".


File.GetAttributes Examples

File.GetAttributes

table File.GetAttributes (

string Filename )

Example 1

all_attributes = File.GetAttributes(_ProgramFilesFolder.."\\Setup Factory XX\\SUFDesign.exe");

Stores all of the attributes of the file named "SUFDesign.exe" in a table called "all_attributes."

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files directory.

Example 2

attrib = File.GetAttributes( _TempFolder .. "\\MyTempFile.tmp" );
bReadOnly = attrib.ReadOnly;
strCreationDate = attrib.CreationDate;

Stores the attributes of the MyTempFile.tmp file located in the user's temp folder in a table named attrib, then copies the ReadOnly attribute into a boolean variable named bReadOnly, and copies the file's creation date string into a variable named strCreationDate.

Example 3

-- Get the file attributes from MyTempFile.tmp, located in the temp directory
attrib = File.GetAttributes( _TempFolder .. "\\MyTempFile.tmp" );

if attrib.ReadOnly then
-- The file is read only, alert the user
Dialog.Message("Read-Only", "The file you are trying to access is read only.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end

Retrieves the attributes of the file "MyTempFile.tmp" and alerts the user if the file has it's read-only attribute set.


File.GetCRC Examples

File.GetCRC

number File.GetCRC (

string Filename )

Example 1

CRC_check = File.GetCRC(_TempFolder .. "\\setup.exe");

Gets the CRC value of the file "setup.exe" located in the user's Temp directory and stores it in the variable "CRC_check."

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Check to see if the user is connected to the internet
connected = HTTP.TestConnection("http://www.indigorose.com", 20, 80, nil, nil);

-- If they are connected.
if connected then
-- Download a file to their temporary directory.
StatusDlg.Show(MB_ICONNONE, false);
HTTP.Download("http://www.indigorose.com/setup.exe", _TempFolder.."\\setup.exe", MODE_BINARY, 20, 80, nil, nil, nil);

-- Get any error codes that may have been returned by the download action.
error = Application.GetLastError();
StatusDlg.Hide();

-- If there was an error during the download, display the error message.
if error ~= 0 then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If there was no error during the download.
else
--Get the CRC value of the downloaded file.
crc_value = File.GetCRC(_TempFolder.."\\setup.exe");
-- Check to see if the CRC value matches it's expected value.
if crc_value == 824907888 then

-- Run the exectuable that was downloaded.
File.Run(_TempFolder.."\\setup.exe", "", "", SW_SHOWNORMAL, true);

-- The CRC value does not match. Display an error message to the user.
else
result = Dialog.Message("Error", "The downloaded file is incomplete. Please try downloading again.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end
end

-- Display a notice informing them that they are not connected.
else
Dialog.Message("Internet Error", "You are not connected to the internet. Please connect to download.");
end

This example first checks to see if the user has an internet connection. If they do, a file is downloaded to their temporary directory. That file is then checked to make sure it is complete and not corrupt before launching it. This validation on the file is accomplished using the File.GetCRC action. A series of checks are performed in this script to handle any errors that occur and displays notification messages to the user if any actions fail.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


File.GetDefaultViewer Examples

File.GetDefaultViewer

string File.GetDefaultViewer (

string FileExtension )

Example 1

pdf_viewer = File.GetDefaultViewer(".pdf");

Gets the path to the program that is used by default to view PDF files on the user's system, and stores it in the pdf_viewer variable.

Example 2

default_text_editor = File.GetDefaultViewer(".txt");

Gets the path to the user's default viewer for text files, and stores it in a variable called default_text_editor.

Example 3

-- Get the default viewer for files with the extension .sf7.
viewer_path = File.GetDefaultViewer(".sf7");

-- If there is no program association for .sf7, display a message.
-- If there is, get the directory where the program is located.
if viewer_path == "" then
result = Dialog.Message("Notice", "There is no program association for the .sf7 file extension.", MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
else
-- Split the path into drive, folder and filename to store in a table.
tbPath = String.SplitPath(viewer_path);

-- Concatenate the drive and folder parts.
Folder_Path = String.Concat(tbPath.Drive, tbPath.Folder);

-- Display the path to the user.
result = Dialog.Message("Target Path", "The associated program is located in "..Folder_Path, MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end

Gets the path to the user's default viewer for files with the extension .sf7 in order to get the directory of that program. If there is no program association for that file type, a message is shown to the user. If there is, the drive and folder is extracted and shown to the user.


File.GetShortName Examples

File.GetShortName

string File.GetShortName (

string Filename )

Example 1

short_version = File.GetShortName ("C:\\Program Files\\Setup Factory 9\\SUFDesign.exe");

Gets the "8.3" version of the file path "C:\Program Files\Setup Factory 9\SUFDesign.exe" and stores it in the variable "short_version." The result will look similar to "C:\PROGRA~1\SETUPF~1\SUFDES~1.EXE."


File.GetSize Examples

File.GetSize

number File.GetSize (

string Filename )

Example 1

file_size = File.GetSize(_TempFolder .. "\\setup.exe");

Gets the size (in bytes) of the file "setup.exe" located in the user's Temp directory and stores it in the variable "file_size."

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Searches for a specific file on the user's system.
location = File.Find("C:\\", "target.txt", false, false, nil);

if (location ~= nil) then
-- Check the size of the first file that was found.
file_size = File.GetSize(location[1]);

if (file_size ~= -1) then
-- See if the file is 25 bytes. Display a valid or invalid file message to the user.
if (file_size == 25) then
Dialog.Message("Success", "The file on your system has been validated.");
else
Dialog.Message("Failure", "The file on your system is not valid.");
end
else
Dialog.Message("Failure", "The file on your system could not be validated.");
end
else
-- Display a message that the target file was not found.
Dialog.Message("Notice","The file 'target.txt' was not found.");
end

Searches for a file called "target.txt" in the root of the C:\ drive. If the file is found, its file size is read and compared to the value 25 bytes. Based on the validation results, an appropriate dialog message is displayed.

Example 3

g_FolderSize = 0;

-- This function determines the size of a file and adds it to the total.
-- This function is used as the callback function for the File.Find action in this example.
function OnFileFound(Path)
local nSize = File.GetSize(Path);
g_FolderSize = g_FolderSize + nSize;
return true;
end

-- Allow the user to browse for a folder whose size they want.
local strFolder = Dialog.FolderBrowse("Find a folder",Shell.GetFolder(SHF_MYDOCUMENTS));

StatusDlg.Show();
tblFiles = File.Find(strFolder,"*.*",true,false,nil,OnFileFound);
StatusDlg.Hide();
Dialog.Message("Size",String.GetFormattedSize(g_FolderSize));

This example calculates the total size of a selected folder's contents. To accomplish this, the File.Find action is called with the callback function called "OnFileFound".


File.GetVersionInfo Examples

File.GetVersionInfo

table File.GetVersionInfo (

string Filename )

Example 1

version_info = File.GetVersionInfo( _ProgramFilesFolder .. "\\Doopernator\\Doopernator.exe");
fv = version_info.FileVersion;
pv = version_info.ProductVersion;

Gets the version info for the "C:\Program Files\Doopernator\Doopernator.exe" file and stores it in a table named version_info. Then copies the file version and product version from that table into variables named fv and pv, respectively.

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files directory.

Example 2

-- Get the file information, and load it into a table
tVersionInfo = File.GetVersionInfo(_SourceFolder .. "\\setup.exe");

-- Get the last error code
nError = Application.GetLastError();
if nError == 0 then
-- There was not an error
sOutput = "";

-- Traverse the table, storing info in a string
for Name, Contents in pairs(tVersionInfo) do
sOutput = sOutput .. Name .. ": " .. Contents .. "\r\n";
end

-- Output string contents to the user
Dialog.Message("File Version Information", sOutput);
else
-- There was an error, alert the user
Dialog.Message("Error", _tblErrorMessages[nError]);
end

Retrieves the version information from the file "setup.exe, and presents it to the user in a single dialog message.

Note: _SourceFolder is a built-in variable that contains the path to the location the setup.exe is run from.


File.Install Examples

File.Install

boolean File.Install (

string Filename,

string Destination,

number Overwrite = 0,

boolean CreateBackup = false,

boolean SharedSystem = false,

function ProgressCallbackFunction = nil,

function OverwriteCallbackFunction = nil )

Example 1

-- Install the file cooltoy.dll.
success = File.Install(_TempFolder.."\\cooltoy.dll", _SystemFolder.."\\cooltoy.dll", FILE_INSTALL_ALWAYS, false, false, nil, nil );

-- Check to see if the install action was successful by getting an error code.
error = Application.GetLastError();

-- If the install was not successful, display it's error message.
if success == false then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Installs the "cooltoy.dll" file to the user's System folder, overwriting any existing cooltoy.dll file that might be there. Stores true or false in a variable named "success" according to whether or not the file was successfully installed. If it failed, the error code message is shown in a dialog message.


File.IsInUse Examples

File.IsInUse

boolean File.IsInUse (

string Filename )

Example 1

are_ya_busy = File.IsInUse(_WindowsFolder.."\\targetfile.exe");

Stores true in a variable named "are_ya_busy" if the "targetfile.exe" file is in use in the user's Windows directory.

Note: _WindowsFolder is a built-in variable that contains the path to the user's Windows directory.

Example 2

-- Checks to see if a particular file exists.
are_ya_there = File.DoesExist(_WindowsFolder.."\\targetfile.exe");

-- If the file exists, check to see if the file is in use.
if (are_ya_there) then
are_ya_busy = File.IsInUse(_WindowsFolder.."\\targetfile.exe");

-- If the file isn't in use, overwrite the file.
if (are_ya_busy == false) then
File.Copy(_TempFolder.."\\targetfile.exe", _WindowsFolder.."\\targetfile.exe", false, true, false, true, nil);

-- If the file is in use, notify the user.
else
result = Dialog.Message("Notice", "The specified file could not be overwritten.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
end

This example first checks to see if a file called "targetfile.exe" exists. If it exists, a check is performed using the File.IsInUse action to determine if the file is in use. If it isn't in use, another file of the same name is copied over it. If it is in use, a dialog message is shown to notify the user.


File.Move Examples

File.Move

File.Move (

string Source,

string Destination,

boolean Recurse = true,

boolean Overwrite = true,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Example 1

File.Move(_TempFolder.."\\Text Files\\*.txt", _TempFolder .. "\\Text Files Backup", false);

Moves all of the text files in the "Text Files" folder into a folder called "Text Files Backup" inside the user's temp folder, and does not go into any subfolders inside "Text Files" as it searches for files to move.

Example 2

File.Move(_SourceFolder .. "\\hidden.dat", _TempFolder .. "\\z3j2rlk\\sneaky.exe", false, true, false, true, CB_Move);

Moves a file named "hidden.dat" from the folder where the setup.exe is located, to a folder named "z3j2rlk" in the user's temp folder, renaming the file to "sneaky.exe" in the process. The recurse option is turned off, and the other boolean parameters are set to their default values. A function named CB_Move will be called whenever progress is made in the move operation (i.e. every time x number of bytes are moved).

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 3

-- Get the path to the user's My Documents folder.
myDocsFolder = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Create a folder in the user's My Documents folder.
Folder.Create(myDocsFolder.."\\New");

-- Show the status dialog.
StatusDlg.Show();

-- Move all files from the "Old" folder to the "New" folder.
File.Move(myDocsFolder.."\\Old\\*.*", myDocsFolder.."\\New", true, true, false, false, nil);

-- Check to see if the files moved successfully by getting the error code.
error = Application.GetLastError();

-- Hide the status dialog.
StatusDlg.Hide();

-- If there was an error, display the error message.
-- If no error occurred, open the folder to view the moved files.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OKCANCEL, MB_ICONEXCLAMATION);
else
File.ExploreFolder(myDocsFolder.."\\New");
end

This example first creates a new folder in the user's My Documents folder called "New." The File.Move action is then called to move all files from an existing folder called "Old" to the folder called "New." If the file move fails, the error code message is shown and if it succeeds, the folder is opened in an explore window.


File.MoveOnReboot Examples

File.MoveOnReboot

File.MoveOnReboot (

string Source,

string Destination )

Example 1

File.MoveOnReboot(_TempFolder .. "\\setup.exe", "C:\\setup.exe");

On the next system reboot the file "setup.exe" located in the user's temporary directory will be moved to "C:\setup.exe."

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


File.Open Examples

File.Open

File.Open (

string Filename,

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL )

Example 1

File.Open(SessionVar.Expand("%AppFolder%\\chapter3.rtf"), "", SW_MAXIMIZE);

Opens "chapter3.rtf" located in the user's application folder in the user's default viewer for RTF files (probably Word), and maximizes the viewer program's window.

Note: In order to expand the session variable %AppFolder% in an action, the action SessionVar.Expand must be used.

Example 2

File.Open(_TempFolder.."\\Documents\\readme.txt", "", SW_SHOWNORMAL);

Opens "Documents\readme.txt" (located in the system Temp folder) in the user's default viewer for TXT files (probably Notepad), and opens the viewer program's window normally (not minimized or maximized).

Example 3

File.Open(SessionVar.Expand("%MyDocumentsFolder%\\secretplans.pdf"), SessionVar.Expand("%MyDocumentsFolder%"));

Opens the "secretplans.pdf" file, located in the user's My Documents folder, using the user's default viewer for PDF files (probably Acrobat). Tells the default viewer to use the My Documents folder as the working folder.

Note: In order to expand the session variable %MyDocumentsFolder% in an action, the action SessionVar.Expand must be used. The path to the user's My Documents folder could also be retrieved using the Shell.GetFolder action.


File.OpenEmail Examples

File.OpenEmail

File.OpenEmail (

string EmailAddress,

number WindowMode = SW_SHOWNORMAL )

Example 1

File.OpenEmail("sales@indigorose.com?subject=I need help", SW_MAXIMIZE);

Opens the user's default email client, with "sales@indigorose.com" in the To: field and "I need help" in the subject line, and maximizes the email client's program window.

Example 2

File.OpenEmail("foo@bar.com");

Opens the user's default email client, with "foo@bar.com" in the To: field. The email program's window is opened normally (not minimized or maximized).

Example 3

File.OpenEmail("consulting@indigorose.com?subject=Thanks%21");

Sends an email to consulting@indigorose.com, using the user's default email client, with "Thanks!" automatically entered in the subject line.

Note: The exclamation mark is URL encoded as %21 because ! is a special character in URLs.


File.OpenURL Examples

File.OpenURL

File.OpenURL (

string URL,

number WindowMode = SW_SHOWNORMAL )

Example 1

File.OpenURL("www.indigorose.com", SW_MAXIMIZE);

Opens the Indigo Rose home page in the user's default browser, and maximizes the browser's window.

Example 2

File.OpenURL(_SourceFolder.."\\readme.htm");

Opens the file "readme.htm" located in the source folder in the user's default browser, and opens the browser's window normally (not minimized or maximized).

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 3

File.OpenURL("http://www.indigorose.com/forums/");

Opens the Indigo Rose Software user forums in the user's default browser.


File.Print Examples

File.Print

File.Print (

string Filename )

Example 1

File.Print(SessionVar.Expand("%AppFolder%\\catalogue.pdf"));

Prints the file "catalogue.pdf" located in the application folder with the user's default viewer for PDF files (probably Acrobat).

Note: In order to expand the session variable %AppFolder% in an action, the action SessionVar.Expand must be used.

Example 2

File.Print("C:\\instructions.doc");

Prints "C\instructions.doc" with the user's default viewer for DOC files (probably Word).

Example 3

-- Print the specified file.
File.Print(_TempFolder.."\\MyFile.pdf");

--Check to see if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Prints the file "MyFile.pdf" located in the user's system Temp folder with the user's default viewer for PDF files (probably Acrobat). If the action fails, the error code message is displayed in a dialog message.


File.Rename Examples

File.Rename

File.Rename (

string OldName,

string NewName )

Example 1

File.Rename("C:\\Temporary Stored\\index.txt", "C:\\Temporary Stored\\updated.txt");

Renames "index.txt" located at "C:\Temporary Stored\index.txt" to "updated.txt."

Example 2

-- Rename the specified file.
File.Rename("C:\\OldFile.ext", "C:\\NewFile.ext");

--Check to see if an error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Renames the file "OldFile.ext" to "NewFile.ext" and checks to see if the action failed. If it failed, the error code message is displayed in a dialog message.


File.Run Examples

File.Run

number File.Run (

string Filename,

string Args = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false )

Example 1

ReturnCode = File.Run(_TempFolder.."\\setup.exe", "/w", "", SW_MAXIMIZE, true);

Runs "setup.exe" located in the user's Temp folder, passes it /w as a command line argument, tells it to open with its window maximized, and waits for setup.exe to exit before continuing with the next action. Any code returned by "setup.exe" is stored in variable "ReturnCode".

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

File.Run("notepad.exe", _SourceFolder.."\\Docs\\readme.txt", "C:\\Temp", SW_SHOWNORMAL, true);

Runs notepad.exe and opens "Docs\readme.txt" in it which is located in the source folder. Specifies C:\Temp as the working directory, tells notepad to open with its normal window size and position, and waits for the user to close notepad.exe before continuing.

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 3

-- Confirm that the installation executable should be launched.
result = Dialog.Message("Confirm", "Are you sure you would like to install now?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- If the user clicked the Yes button.
if (result == IDYES) then

-- Run the installation file.
File.Run(_TempFolder.."\\Second_Install\\setup.exe", "", "", SW_SHOWNORMAL, false);

-- Check to see if an error occurred when launching the file.
error = Application.GetLastError();

-- If an error occurred, display an error message to the user.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
end

Asks the user if they would like to run the installation file. If they click the Yes button, the installation file will be launched using the File.Run action. If the action fails, the error code message is displayed in a dialog message.

Example 4

-- Get the session variable and assign it to a regular variable
AppDir = SessionVar.Expand("%AppFolder%");

-- Run the file using the AppDir variable
File.Run(AppDir.."\\Myfile.exe", "", "", SW_SHOWNORMAL, false);

-- This could also be done as such
File.Run(SessionVar.Expand("%AppFolder%").."\\Myfile.exe", "", "", SW_SHOWNORMAL, false);

This example shows two ways of using a File.Run action with a session variable.


File.RunAs Examples

File.RunAs

number File.RunAs (

string Filename,

string Args = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false,

string UserName = "",

string Password = "",

string Domain = "",

number LogonFlag = LOGON_NO_OPTION,

table CreationOptions = nil,

table ExtendedErrorInfo = nil )

Example 1

ReturnCode = File.RunAs(_TempFolder.."\\setup.exe", "/W", "", SW_SHOWNORMAL, true, "TestUser", "fake_password", "", LOGON_NO_OPTION, nil, nil);

Runs "setup.exe" located in the user's Temp folder using "TestUser" user permissions, passes it /W as a command line argument, and waits for setup.exe to exit before continuing with the next action. Any code returned by "setup.exe" is stored in variable "ReturnCode".

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Create the extended error info table.
ExtendedErrorInfo = {};

-- Run the file as an administrator.
nReturnCode = File.RunAs(_TempLaunchFolder.."\\SetupTest.exe", "/W", "", SW_SHOWNORMAL, true, "Administrator", "master_password", "work.fakedomain.com", LOGON_WITH_PROFILE, nil, ExtendedErrorInfo);
error = Application.GetLastError();

-- Check if the action succeeded or failed and display the error messages.
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error].."\r\n"..ExtendedErrorInfo.ErrorCode..": "..ExtendedErrorInfo.ErrorMsg);
end

Runs "SetupTest.exe" located in the installer's Temp folder using "Administrator" user permissions, passes it /W as a command line argument, and waits for SetupTest.exe to exit before continuing with the next action. Any code returned by "setup.exe" is stored in variable "ReturnCode" and if an error occurs, the error code and messages are shown in a dialog message.


File.RunOnReboot Examples

File.RunOnReboot

File.RunOnReboot (

string Filename,

string Args = "" )

Example 1

File.RunOnReboot(_TempFolder .. "\\setup.exe", "/W");

On the next system reboot the file "setup.exe" located in the user's temporary directory will be run with the command line argument "/W."

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


File.SetAttributes Examples

File.SetAttributes

File.SetAttributes (

string Filename,

table Attributes )

Example 1

-- get the file's current attributes
attrib = File.GetAttributes( _TempFolder .. "\\MyTempFile.tmp" );

-- override a couple of the values in the table
attrib.ReadOnly = true;
attrib.Hidden = false;

-- set the modified attributes back to the file
File.SetAttributes( _TempFolder .. "\\MyTempFile.tmp", attrib );

Sets the ReadOnly attribute and unsets the Hidden attribute of the MyTempFile.tmp file located in the user's temp folder, leaving all other attributes the same.

Example 2

-- create an empty table
attrib = {};

-- add two elements to it ("ReadOnly" and "Hidden")
attrib.ReadOnly = true;
attrib.Hidden = false;

-- apply those attributes to the file
File.SetAttributes( _TempFolder .. "\\MyTempFile.tmp", attrib );

This does the same thing as example 1: it sets the ReadOnly attribute and unsets the Hidden attribute of the MyTempFile.tmp file located in the user's temp folder, leaving all other attributes the same.

Example 3

-- change two attributes in the file by creating a table "on the fly"
File.SetAttributes( _TempFolder .. "\\MyTempFile.tmp", {ReadOnly=true, Hidden=false} )

This does the same thing as examples 1 and 2: it sets the ReadOnly attribute and unsets the Hidden attribute of the MyTempFile.tmp file located in the user's temp folder, leaving all other attributes the same.

Note: The {ReadOnly=true, Hidden=false} part creates a "temporary" table with ReadOnly and Hidden elements set to true and false, respectively. This is just like creating a named table (like attrib in the examples above) and then passing it to the action by its name. The only difference is that this table doesn't have a name. It's basically just a one-off.


File.SetPermissions Examples

File.SetPermissions

number File.SetPermissions (

string Filename,

string UserSID = SID_EVERYBODY,

number AccessMode = SET_ACCESS,

number Permissions = ALL_PERMISSIONS,

number Inheritance = SUB_CONTAINERS_AND_OBJECTS_INHERIT )

Example 1

-- Set the permissions of the file to everyone.
strCommonProductFile = Shell.GetFolder(SHF_APPLICATIONDATA_COMMON).."\\MyFile.txt";
File.SetPermissions(strCommonProductFile, SID_EVERYBODY, SET_ACCESS, ALL_PERMISSIONS, SUB_CONTAINERS_AND_OBJECTS_INHERIT);

Sets the permissions of the file "MyFile.txt" located in the common application data folder to full access permissions by everyone.

Example 2

-- Set the permissions of the product folder in application data common to everyone.
strCommonProductFolder = Shell.GetFolder(SHF_APPLICATIONDATA_COMMON).."\\MyProductFolder";
File.SetPermissions(strCommonProductFolder, SID_EVERYBODY, SET_ACCESS, ALL_PERMISSIONS, SUB_CONTAINERS_AND_OBJECTS_INHERIT);

Sets the permissions of the folder "MyProductFolder" located in the common application data folder to full access permissions by everyone.


Folder.Create Examples

Folder.Create

Folder.Create (

string Folder )

Example 1

Folder.Create("C:\\Stored");

Creates a new folder called "Stored" on the user's C: drive.

Example 2

Folder.Create(_ProgramFilesFolder.."\\Flashy");

Creates a new folder called "Flashy" in the user's Program Files folder.

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files folder.

Example 3

-- Get the path to the user's My Documents folder.
myDocsFolder = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Create a folder in the user's My Documents folder.
Folder.Create(myDocsFolder.."\\New");

-- Show the status dialog.
StatusDlg.Show();

-- Move all files from the "Old" folder to the "New" folder.
File.Move(myDocsFolder.."\\Old\\*.*", myDocsFolder.."\\New", true, true, false, false, nil);

-- Check to see if the files moved successfully by getting the error code.
error = Application.GetLastError();

-- Hide the status dialog.
StatusDlg.Hide();

-- If there was an error, display the error message.
-- If no error occurred, open the folder to view the moved files.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OKCANCEL, MB_ICONEXCLAMATION);
else
File.ExploreFolder(myDocsFolder.."\\New");
end

This example first creates a new folder in the user's My Documents folder called "New." The File.Move action is then called to move all files from an existing folder called "Old" to the folder called "New." If the file move fails, the error code message is shown and if it succeeds, the folder is opened in an explore window.


Folder.Delete Examples

Folder.Delete

Folder.Delete (

string Folder )

Example 1

Folder.Delete("C:\\Stored");

Deletes a folder called "Stored" from the user's C: drive.

Example 2

Folder.Delete(_ProgramFilesFolder.."\\Flashy");

Deletes a folder called "Flashy" from the user's Program Files folder.

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files folder.

Example 3

-- Get the path to the user's My Documents folder.
myDocsFolder = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Delete the folder.
Folder.Delete(myDocsFolder.."\\Partial Backup");

-- Check to see if any errors were generated from the delete.
error = Application.GetLastError();

-- Check to see if the deletion failed due to files being present.
if error == 2203 then
-- Remove all of the contents of the folder.
File.Delete(myDocsFolder.."\\Partial Backup\\*.*", true, false, false, nil);

-- Attempt to remove the folder again.
Folder.Delete(myDocsFolder.."\\Partial Backup");

-- Check to see if the action failed.
error = Application.GetLastError();

-- Notify the user that the folder couldn't be deleted.
if (error ~= 0) then
Dialog.Message("Error", "The folder could not be deleted.", MB_OK, MB_ICONEXCLAMATION);
end
end

Tries to delete the folder called "Partial Backup" in the user's My Documents folder. If the action failed because the folder was not empty, all of the files will be deleted. After the files have been deleted, another attempt to remove the folder is performed.


Folder.DeleteTree Examples

Folder.DeleteTree

Folder.DeleteTree (

string FolderName,

function CallbackFunction = nil )

Example 1

Folder.DeleteTree("C:\\TargetFolder", nil);

Deletes the folder called "TargetFolder" and all of its contents.

Example 2

-- Display a browse dialog so they can select a folder they want deleted.
target_folder = Dialog.FolderBrowse("Locate Folder", _DesktopFolder);

if (target_folder ~= "CANCEL") and (target_folder ~= "") then
-- Ask the user to confirm the deletion of the folder and its contents.
result = Dialog.Message("IMPORTANT", "Are you sure you wish to delete the folder located at "..target_folder.."?\r\n\r\nClicking 'Yes' will remove the folder and all of its contents.", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);

if (result == IDYES) then
-- Show the status dialog.
StatusDlg.Show();

-- Delete the target folder and all of its contents.
Folder.DeleteTree(target_folder);

-- Hide the status dialog.
StatusDlg.Hide();
end
end

A folder browse dialog is displayed allowing the user to select a folder they wish to delete. Once selected, the user is presented with a confirmation dialog explaining the implications of the action. If they click the "Yes" button, the target folder and all of its contents are deleted.


Folder.DoesExist Examples

Folder.DoesExist

boolean Folder.DoesExist (

string Folder )

Example 1

does_exist = Folder.DoesExist("C:\\Magic");

Stores true in a variable named "does_exist" if the "Magic" folder exists at "C:\Magic", and false if it doesn't.

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files folder.

Example 2

bIs_There = Folder.DoesExist(_ProgramFilesFolder..\\Setup Factory XX");

Checks to see if the folder "Setup Factory XX" exists in the user's Program Files folder and stores either true or false accordingly in the variable "bIs_There." The concatenation operator (..) is used here to concatenate the Program Files folder path with "\Setup Factory XX."

Tip: Starting a variable name with "b" is a technique that programmers use to help themselves remember that a variable contains a boolean value.

Example 3

-- Check to see if a specific folder exists.
does_exist = Folder.DoesExist(_ProgramFilesFolder);

-- Display a dialog telling the user whether or not the folder exists.
if does_exist then
Dialog.Message("Notice", "Yes, the folder does exist on your system.", MB_OK, MB_ICONINFORMATION);
else
Dialog.Message("Notice", "No, the folder does not exist on your system.", MB_OK, MB_ICONINFORMATION);
end

Checks to see if the Program Files folder exists on the user's machine and notifies the user using a dialog message.


Folder.Find Examples

Folder.Find

table Folder.Find (

string StartFolder,

string Folder,

boolean Recurse = false,

function CallbackFunction = nil )

Example 1

ImageFolders = Folder.Find( _SourceFolder, "*Images*", true, ShowSearchProgress);

Searches for all folders inside the folder that the installation is running, that contain "Images" in the name, and stores their paths in a table called ImageFolders. Since Recurse is true, the action will search inside subfolders. The function named ShowSearchProgress will be called whenever progress is made in the search operation.

Example 2

found = Folder.Find( Shell.GetFolder(SHF_MYDOCUMENTS),"Plant Data", false);
if (found) then
Dialog.Message("Found one!", "The first folder found was:" .. found[1]);
end

Searches for any folders inside the root of the user's My Documents folder that are named "Plant Data", and stores their paths in a table named "found." Then, the example tests that table to see if there were any folders stored in it (if there weren't, it would have been set to nil by the Folder.Find action), and if there are, puts up a message dialog to show the path to the first folder that was found.


Folder.GetCurrent Examples

Folder.GetCurrent

string Folder.GetCurrent (

)

Example 1

current_dir = Folder.GetCurrent( );

Gets the current working directory for the installation and stores the path in the variable "current_dir."


Folder.Rename Examples

Folder.Rename

Folder.Rename (

string OldName,

string NewName )

Example 1

Folder.Rename("C:\\Stored", "C:\\OldStored");

Renames the folder located at "C:\Stored" to "C:\OldStored."

Example 2

Folder.Rename(_ProgramFilesFolder .."\\My Application\\Data", _ProgramFilesFolder .."\\My Application\\DataBK");

Renames the "Data" folder located in the My Application folder to "DataBK."

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files folder.

Example 3

-- Renames a current folder.
Folder.Rename("C:\\My Folder", "C:\\My New Folder");

-- Get the error code for the rename action.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Renames "My Folder" to "My New Folder" and displays an error message if the action fails.


Folder.SetCurrent Examples

Folder.SetCurrent

Folder.SetCurrent (

string Folder )

Example 1

Folder.SetCurrent(_TempFolder.."\\Data");

Sets the installation's "current directory" (working directory) to be the "Data" directory located within the user's system Temporary directory.


HTTP.Download Examples

HTTP.Download

HTTP.Download (

string URL,

string Filename,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Example 1

HTTP.Download("http://www.indigorose.com/downloads/sample.zip", SessionVar.Expand("%TempFolder%\\sample.zip")", MODE_BINARY, 20, 80, nil, nil, nil);

Downloads the file "sample.zip" from "http://www.indigorose.com/downloads" into the user's Temporary folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Check to see if the user is connected to the internet
connected = HTTP.TestConnection("http://www.indigorose.com", 20, 80, nil, nil);

-- If they are connected.
if connected then
-- Download a file to their temporary directory.
StatusDlg.Show(MB_ICONNONE, false);
HTTP.Download("http://www.indigorose.com/setup.exe", SessionVar.Expand("%TempFolder%\\setup.exe"), MODE_BINARY, 20, 80, nil, nil, nil);

-- Get any error codes that may have been returned by the download action.
error = Application.GetLastError();
StatusDlg.Hide();
-- If there was an error during the download, display the error message.
if error ~= 0 then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
-- If there was no error during the download.
else
--Get the CRC value of the downloaded file.
crc_value = File.GetCRC(SessionVar.Expand("%TempFolder%\\setup.exe");
-- Check to see if the CRC value matches it's expected value.
if crc_value == 824907888 then

-- Run the exectuable that was downloaded.
File.Run(SessionVar.Expand("%TempFolder%\\setup.exe", "", "", SW_SHOWNORMAL, true);

-- The CRC value does not match. Display an error message to the user.
else
result = Dialog.Message("Error", "The downloaded file is incomplete. Please try downloading again.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end
end
-- Display a notice informing them that they are not connected.
else
Dialog.Message("Internet Error", "You are not connected to the internet. Please connect to download.");
end

This example first checks to see if the user has an internet connection. If they do, a file is downloaded to their temporary directory. That file is then checked to make sure it is complete and not corrupt before launching it. A series of checks are performed in this script to handle any errors that occur and displays notification messages to the user if any actions fail.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 3

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);

-- Continue with the download.
return true;
end

-- Show the StatusDlg
StatusDlg.Show(0, false);

-- Set statusdlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/setup.exe", SessionVar.Expand("%TempFolder%\\setup.exe"), MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the Status Dialog.


HTTP.DownloadSecure Examples

HTTP.DownloadSecure

HTTP.DownloadSecure (

string URL,

string Filename,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Example 1

HTTP.DownloadSecure("https://www.indigorose.com/downloads/sample.zip", _TempFolder.."\\sample.zip", MODE_BINARY, 20, 443, nil, nil, nil);

Downloads the file "sample.zip" from "http://www.indigorose.com/downloads" into the user's Temporary folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

-- Check to see if the user is connected to the internet
connected = HTTP.TestConnection("http://www.indigorose.com", 20, 80, nil, nil);

-- If they are connected.
if connected then
-- Download a file to their temporary directory.
StatusDlg.Show(MB_ICONNONE, false);
HTTP.DownloadSecure("https://www.indigorose.com/setup.exe", _TempFolder.."\\setup.exe", MODE_BINARY, 20, 443, nil, nil, nil);

-- Get any error codes that may have been returned by the download action.
error = Application.GetLastError();
StatusDlg.Hide();

-- If there was an error during the download, display the error message.
if error ~= 0 then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If there was no error during the download.
else
--Get the CRC value of the downloaded file.
crc_value = File.GetCRC(_TempFolder.."\\setup.exe");
-- Check to see if the CRC value matches it's expected value.
if crc_value == 824907888 then

-- Run the exectuable that was downloaded.
File.Run(_TempFolder.."\\setup.exe", "", "", SW_SHOWNORMAL, true);

-- The CRC value does not match. Display an error message to the user.
else
result = Dialog.Message("Error", "The downloaded file is incomplete. Please try downloading again.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end
end

-- Display a notice informing them that they are not connected.
else
Dialog.Message("Internet Error", "You are not connected to the internet. Please connect to download.");
end

This example first checks to see if the user has an internet connection. If they do, a file is downloaded to their temporary directory. That file is then checked to make sure it is complete and not corrupt before launching it. A series of checks are performed in this script to handle any errors that occur and displays notification messages to the user if any actions fail.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 3

-- Callback function for HTTP.DownloadSecure
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);

-- Continue with the download.
return true;
end

-- Set statusdlg title and message
StatusDlg.SetTitle("Downloading . . . ");
StatusDlg.SetMessage("Currently downloading file . . . ");

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Show the StatusDlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.DownloadSecure("https://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 443, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the Status Dialog.


HTTP.GetConnectionState Examples

HTTP.GetConnectionState

table HTTP.GetConnectionState (

)

Example 1

tConnectedState = HTTP.GetConnectionState();

Gets the connection state, and store it in table 'tConnectedState'.

Example 2

-- Used to generate 100 spaces. This allows lining up of boolean values later
function AddSpaces()
strReturn = ""
for nCount = 1, 100 do
strReturn = strReturn .. " ";
end
return strReturn;
end

-- converts boolean value to string (true = True, false = False)
function BoolToString(Value)
if type (Value) == "boolean" then
if Value then return "True" else return "False" end;
else
return Value;
end
end

-- Get the current connection state
tConnectionState = HTTP.GetConnectionState();

-- Initialize string used to store the broken-down details
strStateDetails = "";

-- traverse through tConnectionState, fill in string strStateDetails
for sIndex, vDetails in pairs(tConnectionState) do
strStateDetails = strStateDetails .. String.Mid(sIndex..": ".. AddSpaces(),1, 30).. " " .. BoolToString(vDetails) .. "\r\n";
end

-- Output to user
Dialog.Message("Connection State Results", strStateDetails);

Tests the connection state and outputs the results to the user.


HTTP.GetFileSize Examples

HTTP.GetFileSize

number HTTP.GetFileSize (

string URL,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Example 1

nSize = HTTP.GetFileSize("http://www.mydomain.com/myfile.exe", MODE_BINARY, 20, 80, nil, nil, nil);

Gets the size of the file "myfile.exe" located at "http://www.mydomain.com" and stores it in the variable nSize.

Example 2

-- Settings for HTTP actions
sFileOnServer = "http://www.yourdomain.com/pub/file.ext";
sLocalFilePath = _TempFolder .. "file.ext";
nServerMode = MODE_BINARY;
nServerTimeout = 20;
nServerPort = 80;
tAuthData = nil;
tProxyData = nil;

-- Set the max bytes allowed without alerting the user to 2MB (2*1024*1024):
QuestionByteThreshold = 2097152;

-- Assume download should continue
bContinueDownload = true;

-- Get Filesize of file to be downloaded
FileSize = HTTP.GetFileSize(sFileOnServer, nServerMode, nServerTimeout, nServerPort, tAuthData, tProxyData, nil);

-- Check if filesize is unknown
if FileSize == -1 then
-- Filesize is unknown, alert user
choice = Dialog.Message("Alert", "Filesize is unknown. Continue Download?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);
if choice == 7 then
-- User chose not to continue with download
bContinueDownload = false;
end
-- Check if file size is greater than threshold
elseif FileSize > QuestionByteThreshold then
-- Filesize is larger than threshold, alert the user
choice = Dialog.Message("Alert", "Filesize is greater than the threshold by " .. FileSize - QuestionByteThreshold .. " bytes. Continue Download?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);
if choice == 7 then
-- User chose not to continue with download
bContinueDownload = false;
end
end

-- Check if download should continue
if bContinueDownload then
-- Download File, using built in status dialog
StatusDlg.Show();
StatusDlg.ShowCancelButton();
HTTP.Download(sFileOnServer, sLocalFilePath, nServerMode, sServerPass, nServerPort, tAuthData, tProxyData, nil);
StatusDlg.Hide();
else
-- Don't download file, alert user that download has been terminated
Dialog.Message("Alert", "Download aborted by user");
end

Checks the size of a file on a HTTP server to be downloaded. If the file is larger than a predefined threshold, the user is asked if the download should continue.


HTTP.GetFileSizeSecure Examples

HTTP.GetFileSizeSecure

number HTTP.GetFileSizeSecure (

string URL,

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil,

function CallbackFunction = nil )

Example 1

nFileSize = HTTP.GetFileSizeSecure("https://www.mydomain.com/myfile.exe", MODE_BINARY, 20, 443, nil, nil, nil);

Gets the size of the file "myfile.exe" on the secure Web site and stores it in the variable nFileSize.

Example 2

-- Settings for HTTP actions
sFileOnServer = "https://www.yourdomain.com/pub/file.ext";
sLocalFilePath = _TempFolder .. "file.ext";
nServerMode = MODE_BINARY;
nServerTimeout = 20;
nServerPort = 443;
tAuthData = nil;
tProxyData = nil;

-- Set the max bytes allowed without alerting the user to 2MB (2*1024*1024):
QuestionByteThreshold = 2097152;

-- Assume download should continue
bContinueDownload = true;

-- Get Filesize of file to be downloaded
FileSize = HTTP.GetFileSizeSecure(sFileOnServer, nServerMode, nServerTimeout, nServerPort, tAuthData, tProxyData, nil);

-- Check if filesize is unknown
if FileSize == -1 then
-- Filesize is unknown, alert user
choice = Dialog.Message("Alert", "Filesize is unknown. Continue Download?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);
if choice == 7 then
-- User chose not to continue with download
bContinueDownload = false;
end
-- Check if filesize is greater than threshold
elseif FileSize > QuestionByteThreshold then
-- Filesize is larger than threshold, alert the user
choice = Dialog.Message("Alert", "Filesize is greater than the threshold by " .. FileSize - QuestionByteThreshold .. " bytes. Continue Download?", MB_YESNO, MB_ICONQUESTION, MB_DEFBUTTON1);
if choice == 7 then
-- User chose not to continue with download
bContinueDownload = false;
end
end

-- Check if download should continue
if bContinueDownload then
-- Download File, using built in status dialog
StatusDlg.Show();
StatusDlg.ShowCancelButton();
HTTP.DownloadSecure(sFileOnServer, sLocalFilePath, nServerMode, sServerPass, nServerPort, tAuthData, tProxyData, nil);
StatusDlg.Hide();
else
-- Don't download file, alert user that download has been terminated
Dialog.Message("Alert", "Download aborted by user");
end

Checks the size of a file on a HTTPS server to be downloaded. If the file is larger than a predefined threshold, the user is asked if the download should continue.


HTTP.GetHTTPErrorInfo Examples

HTTP.GetHTTPErrorInfo

table HTTP.GetHTTPErrorInfo (

)

Example 1

ErrInfo = HTTP.GetHTTPErrorInfo();

Gets the last HTTP error info and stores it in table ErrInfo.

Example 2

HTTP.Download("http://www.asitehere.com/file.ext", "c:\\file.ext",MODE_BINARY, 20, 80, nil, nil, nil);

if (Application.GetLastError() ~= 0) then

local http_error = HTTP.GetHTTPErrorInfo();
local error_text = http_error.Message .. "\r\nServer Status: " .. http_error.Status;

Dialog.Message("HTTP Error: " .. http_error.Number, error_text, MB_OK, MB_ICONEXCLAMATION);
end

Downloads a file. If an error occurs, displays the extended HTTP error information.

Example 3

HTTP.Download("http://www.asitehere.com/file.ext", "c:\\file.ext",MODE_BINARY, 20, 80, nil, nil, nil);

local http_error = HTTP.GetHTTPErrorInfo();

if (http_error.Status < 200 or http_error.Status > 299) then

-- Write the HTTP error info into the log file
SetupData.WriteToLogFile("HTTP Download Error Info: " .. http_error.Number .. " - " .. http_error.Message, true);
SetupData.WriteToLogFile("HTTP Download Server Status: " .. http_error.Status, true);
end

Downloads a file. If the server status indicates that an error occurred, makes an entry in the installation log file.


HTTP.Submit Examples

HTTP.Submit

string HTTP.Submit (

string URL,

table Values,

number Method = SUBMITWEB_GET,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil )

Example 1

myvalues = {Name="Brian", Company="Indigo Rose"};
result = HTTP.Submit("http://www.indigorose.com/myscript.php", myvalues, SUBMITWEB_GET, 20, 80, nil, nil);

The first line of code creates a table called "myvalues" containing two named value pairs. The first index of the table is "Name,"and has the associated value "Brian." The second index is "Company" and it's associated value is "Indigo Rose." The named value pairs in this table are then submitted to the script located at "http://www.indigorose.com/myscript.php" using an HTTP.Submit action.

Example 2

sResult = HTTP.Submit("http://www.mysearchengine.com/search.php", {search="SetupFactory"}, SUBMITWEB_GET, 20, 80, nil, nil);

This example submits the query "SetupFactory" to a script found at http://www.mysearchengine.com. The parameter is passed using an inline table, and the results are stored in the variable sResult.


HTTP.SubmitSecure Examples

HTTP.SubmitSecure

string HTTP.SubmitSecure (

string URL,

table Values,

number Method = SUBMITWEB_GET,

number Timeout = 20,

number Port = 443,

table AuthData = nil,

table ProxyData = nil )

Example 1

myvalues = {Name="Brian", Company="Indigo Rose"};
result = HTTP.SubmitSecure("https://www.indigorose.com/myscript.php", myvalues, SUBMITWEB_GET, 20, 443, nil, nil);

The first line of code creates a table called "myvalues" containing two named value pairs. The first index of the table is "Name,"and has the associated value "Brian." The second index is "Company" and it's associated value is "Indigo Rose." The named value pairs in this table are then submitted to the script located at "https://www.indigorose.com/myscript.php" using an HTTP.SubmitSecure action.

Example 2

sResult = HTTP.SubmitSecure("https://www.mysearchengine.com/search.php", {search="SetupFactory"}, SUBMITWEB_GET, 20, 443, nil, nil);

This example submits the query "SetupFactory" to a script found at https://www.mysearchengine.com. The parameter is passed using an inline table, and the results are stored in the variable sResult.


HTTP.TestConnection Examples

HTTP.TestConnection

boolean HTTP.TestConnection (

string URL,

number Timeout = 20,

number Port = 80,

table AuthData = nil,

table ProxyData = nil )

Example 1

IsConnected = HTTP.TestConnection("http://www.google.ca", 20, 80, nil, nil);
if (IsConnected == false) then
Dialog.Message("Notice", "No Internet connection was detected.");
end

Checks the user's Internet connection by trying to connect to the site "http://www.google.ca." If the connection fails, a dialog would be displayed notifying the user.

Example 2

-- Check to see if the user is connected to the internet
connected = HTTP.TestConnection("http://www.indigorose.com", 20, 80, nil, nil);

-- If they are connected.
if connected then
-- Download a file to their temporary directory.
StatusDlg.Show(MB_ICONNONE, false);
HTTP.Download("http://www.indigorose.com/setup.exe", _TempFolder.."\\setup.exe", MODE_BINARY, 20, 80, nil, nil, nil);

-- Get any error codes that may have been returned by the download action.
error = Application.GetLastError();
StatusDlg.Hide();

-- If there was an error during the download, display the error message.
if error ~= 0 then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);

-- If there was no error during the download.
else
--Get the CRC value of the downloaded file.
crc_value = File.GetCRC(_TempFolder.."\\setup.exe");
-- Check to see if the CRC value matches it's expected value.
if crc_value == 824907888 then

-- Run the exectuable that was downloaded.
File.Run(_TempFolder.."\\setup.exe", "", "", SW_SHOWNORMAL, true);

-- The CRC value does not match. Display an error message to the user.
else
result = Dialog.Message("Error", "The downloaded file is incomplete. Please try downloading again.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
end
end

-- Display a notice informing them that they are not connected.
else
Dialog.Message("Internet Error", "You are not connected to the internet. Please connect to download.");
end

This example first checks to see if the user has an internet connection using the HTTP.TestConnection action. If they do, a file is downloaded to their temporary directory. That file is then checked to make sure it is complete and not corrupt before launching it. A series of checks are performed in this script to handle any errors that occur and displays notification messages to the user if any actions fail.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


INIFile.DeleteSection Examples

INIFile.DeleteSection

INIFile.DeleteSection (

string Filename,

string Section )

Example 1

INIFile.DeleteSection(_TempFolder .. "\\Configurations.ini", "NumRuns");

Deletes the section called "NumRuns" from the "Configurations.ini" INI file that is currently located in the user's system temp folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


INIFile.DeleteValue Examples

INIFile.DeleteValue

INIFile.DeleteValue (

string Filename,

string Section,

string Value )

Example 1

INIFile.DeleteValue(_TempFolder .. "\\settings.ini", "Columns", "Name" );

Deletes the value called "Name" from the "Columns" section of the "settings.ini" file located in the user's temp folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


INIFile.GetSectionNames Examples

INIFile.GetSectionNames

table INIFile.GetSectionNames (

string Filename )

Example 1

section_names = INIFile.GetSectionNames(_SourceFolder .. "\\settings.ini");

Gets all of the section names within the INI file named "settings.ini" and stores them in a table called "value_names."

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 2

-- Get all of the section names in an INI file.
all_sections = INIFile.GetSectionNames("C:\\Data.ini");

-- Check to see if any error occurred.
error = Application.GetLastError();

-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
found = false;
-- Check to see if any sections are present.
if (all_sections ~= nil) then
-- Go through each section and try to get a value.
for index_section, section in pairs(all_sections) do
-- Try to get the data of the value you want.
value_data = INIFile.GetValue("C:\\Data.ini", section, "Path");

-- If the value was found, modify it's data.
if value_data ~= "" then
INIFile.SetValue("C:\\Data.ini", section, "Path", _ProgramFilesFolder.."\\MyApplication");

-- Check to see if any error occurred.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

found = true;
break;
end
end
end

-- If the value was not found.
if (all_sections == nil) or (not found) then
-- Create a new section with a new value and data.
INIFile.SetValue("C:\\Data.ini", "INSTALL", "Path", _ProgramFilesFolder.."\\MyApplication");

-- Check to see if any error occurred.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end
end

The purpose of this example is to search for a particular value name in an INI file whose section name is unknown. If that value is found, it's data is updated. If it is not found, a new section, value and data is created in the file.


INIFile.GetValue Examples

INIFile.GetValue

string INIFile.GetValue (

string Filename,

string Section,

string Value )

Example 1

value_data = INIFile.GetValue(_SourceFolder .. "\\images.ini", "Water", "Ocean");

Gets the data found in the "Ocean" value located in the "Water" section of the INI file named "images.ini" and stores the result in a variable called "value_data."

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 2

-- Get the value data from an INI file.
full_name = INIFile.GetValue("C:\\Data.ini", "PERSONAL", "Name");

-- Check to see if any errors occurred while calling the action.
error = Application.GetLastError();

-- If an error occurred, display it's error message.
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- If the value was not found, notify the user. If it was, use it in a welcome message.
if (full_name == "") then
Dialog.Message("Notice", "You personal information has not been entered yet.", MB_OK, MB_ICONINFORMATION);
else
Dialog.Message("Hello", "Welcome "..full_name.."!", MB_OK, MB_ICONINFORMATION);
end
end

Retrieves the data found in the "Name" value of the "PERSONAL" section in an INI file. If that value is found, it is used in a welcome dialog. If the value is not found, the user is notified that their information has not yet been saved.


INIFile.GetValueNames Examples

INIFile.GetValueNames

table INIFile.GetValueNames (

string Filename,

string Section )

Example 1

value_names = INIFile.GetValueNames(_SourceFolder .. "\\images.ini", "Water");

Gets all of the value names within the "Water" section of the INI file named "images.ini" and stores them in a table called "value_names."

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 2

-- Get all of the value names in a section of an INI file.
all_values = INIFile.GetValueNames("C:\\Data.ini", "INSTALL");

-- Get the error code of the last action.
error = Application.GetLastError();

-- If an error occurred, display an error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Check to see if there was a value at the second position.
if (all_values[2] ~= nil) then
-- Display the name of the second value in the section.
Dialog.Message("Information", "The second value in the INSTALL section is ".."'"..all_values[2].."'.", MB_OK, MB_ICONINFORMATION);
else
-- Notify the user there is no second value.
Dialog.Message("Information", "There is no second value in the INSTALL section." , MB_OK, MB_ICONINFORMATION);
end
end

Gets all of the value names within the "INSTALL" section of the INI file named "Data.ini" and stores them in a table called "all_values." If there is a second value in the section, it's name is displayed in a dialog. If there is no second value name, a dialog is shown to notify the user.


INIFile.SetValue Examples

INIFile.SetValue

INIFile.SetValue (

string Filename,

string Section,

string Value,

string Data )

Example 1

INIFile.SetValue(_TempFolder .. "\\settings.ini", "Columns", "Name", "Application Path");

-- Get the error code of the last action.
error = Application.GetLastError();

-- If an error occurred, display an error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Sets the string "Application Path" to be the data for the "Name" value in the INI file called "settings.ini" that is located in the user's temp folder. If an error occurs, a dialog is shown with the error code message.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


Math.Abs Examples

Math.Abs

number Math.Abs (

number Num )

Example 1

absolute_num = Math.Abs(-1);

Calculates the absolute value of the number -1 and stores the result in the variable "absolute_num." In this example, the number 1 will be returned.


Math.Acos Examples

Math.Acos

number Math.Acos (

number Num )

Example 1

arccos_num = Math.Acos(0.326960);

Calculates the arccosine of the number 0.326960 and stores the result in the variable "arccos_num." In this example, the number 1.237711350499 will be returned.


Math.Asin Examples

Math.Asin

number Math.Asin (

number Num )

Example 1

arcsine_num = Math.Asin(0.326960);

Calculates the arcsine of the number 0.326960 and stores the result in the variable "arcsine_num." In this example, the number 0.33308497629591 will be returned.


Math.Atan2 Examples

Math.Atan2

number Math.Atan2 (

number Num1,

number Num2 )

Example 1

arctan2_num = Math.Atan2(-862.420000, 78.514900);

Calculates the arctangent of the fraction -862.420000/78.514900 and stores the result in the variable "arctan2_num."

In this example, the number -1.4800063943825 would be returned.


Math.Atan Examples

Math.Atan

number Math.Atan (

number Num )

Example 1

arctan_num = Math.Atan(-862.42);

Calculates the arctangent of the number -862.42 and stores the result in the variable "arctan_num."

In this example, the number -1.5696367994743 will be returned.


Math.Ceil Examples

Math.Ceil

number Math.Ceil (

number Num )

Example 1

ceiling_num = Math.Ceil(2.8);

Calculates the ceiling of the number 2.8 and stores the result in the variable "ceiling_num." In this example, the number 3 will be returned.


Math.Cos Examples

Math.Cos

number Math.Cos (

number Num )

Example 1

cos_num = Math.Cos(1.0);

Calculates the cos of the number 1.0 and stores the result in the variable "cos_num." In this example, the number 0.54030230586814 will be returned.


Math.Deg Examples

Math.Deg

number Math.Deg (

number Radian )

Example 1

rad_to_deg = Math.Deg(1.0);

Converts the radian number 1.0 to a number in degrees and stores the result in the variable "rad_to_deg." In this example the number 57.295779513082 would be returned.


Math.Exp Examples

Math.Exp

number Math.Exp (

number Num )

Example 1

exp_num = Math.Exp(2.302685);

Calculates the exponential of the number 2.302685 and stores the result in the variable "exp_num." In this example, the number 10.000999119968 will be returned.


Math.Floor Examples

Math.Floor

number Math.Floor (

number Num )

Example 1

floor_num = Math.Floor(2.8);

Calculates the floor of the number 2.8 and stores the result in the variable "floor_num." In this example, the number 2 will be returned.


Math.Frexp Examples

Math.Frexp

table Math.Frexp (

number Num )

Example 1

FrExp_num = Math.Frexp(16.4);

Calculates the mantissa and exponent of the number 16.4 and stores them in the table called "FrExp_num." In this example the mantissa value will be 0.5125 and the exponent will be 5. These values can be accessed by referencing FrExp_num.Mantissa and FrExp_num.Exponent.


Math.HexToNumber Examples

Math.HexToNumber

number Math.HexToNumber (

string HexValue )

Example 1

nDecimalValue = Math.HexColorToNumber("FF0000");

Converts the hex value 'FFFF00' to the equivalent decimal value (16711680);


Math.Ldexp Examples

Math.Ldexp

number Math.Ldexp (

number Mantissa,

number Exponent )

Example 1

Ldexp_num = Math.Ldexp(4, 3);

Calculates the value x in the equation x = m * 2^n given that the mantissa (m) is the number 4 and the exponent (n) is the number 3. The result of the calculation will be the number 32, which will be stored in the variable Ldexp_num.


Math.Log10 Examples

Math.Log10

number Math.Log10 (

number Num )

Example 1

log10_num = Math.Log10(9000);

Calculates the base-10 logarithm of the number 9000 and stores the result in the variable "log10_num." In this example, the value 3.9542425094393 will be returned.


Math.Log Examples

Math.Log

number Math.Log (

number Num )

Example 1

log_num = Math.Log(9000);

Calculates the logarithm of the number 9000 and stores the result in the variable "log_num." In this example, the value 9.1049798563184 will be returned.


Math.Max Examples

Math.Max

number Math.Max (

number Num1,

number Num2 )

Example 1

max_num = Math.Max(10, 17);

Compares the number 10 to the number 17 and returns the larger of the two values. In this example the number 17 will be stored in the variable "max_num."


Math.Min Examples

Math.Min

number Math.Min (

number Num1,

number Num2 )

Example 1

min_num = Math.Min(10, 17);

Compares the number 10 to the number 17 and returns the smaller of the two values. In this example the number 10 will be stored in the variable "min_num."


Math.Mod Examples

Math.Mod

number Math.Mod (

number Num1,

number Num2 )

Example 1

mod_num = Math.Mod(10, 3);

Calculates the modulus of 10 / 3 and returns the number 1 in a variable called "mod_num."


Math.Pow Examples

Math.Pow

number Math.Pow (

number Base = 2,

number Exponent = 4 )

Example 1

power = Math.Pow(2,3);

Calculates the base 2 to the power 3 and returns the result in the variable "power." In this example, the number 8 would be returned.


Math.Rad Examples

Math.Rad

number Math.Rad (

number Degree )

Example 1

deg_to_rad = Math.Rad(45);

Converts 45 degrees to it's equivalent value in radians and stores the result in the variable "deg_to_rad." In this example the number 0.78539816339745 will be returned.


Math.Random Examples

Math.Random

number Math.Random (

number Rand1 = nil,

number Rand2 = nil )

Example 1

random_num = Math.Random();

Generates a random value between 0 and 1 (inclusive) and stores the result in the variable "random_num."

Example 2

random_num2 = Math.Random(20);

Generates a random number between 1 and 20 (inclusive) and stores the result in the variable "random_num2."

Example 3

random_num3 = Math.Random(20, 100);

Generates a random number between 20 and 100 (inclusive) and stores the result in the variable "random_num3."


Math.RandomSeed Examples

Math.RandomSeed

Math.RandomSeed (

number Seed )

Example 1

Debug.ShowWindow(true);

Math.RandomSeed(225);
result1 = Math.Random(100);
result2 = Math.Random(100);
result3 = Math.Random(100);
Debug.Print(result1 ..", "..result2..", "..result3.."\r\n");

Math.RandomSeed(225);
result4 = Math.Random(100);
result5 = Math.Random(100);
result6 = Math.Random(100);
Debug.Print(result4 ..", "..result5..", "..result6.."\r\n");

Math.RandomSeed(5647);
result7 = Math.Random(100);
result8 = Math.Random(100);
result9 = Math.Random(100);
Debug.Print(result7 ..", "..result8..", "..result9.."\r\n");

This example seeds the random number generator with the number 225, then calls the Math.Random action three times and outputs the three random numbers to the debug window. Each time this sequence of actions is called, it produces the same sequence of random numbers. Further down in the example, we changed the seed number to 5647. You will notice this results in a different sequence of random numbers. The output from this example will be as follows:

3, 4, 32

3, 4, 32

57, 54, 24

Tip: You can copy and paste this code into the action editor to test it.

Example 2

Debug.ShowWindow(true);

seed_time = System.GetTime(TIME_FMT_SEC)..System.GetTime(TIME_FMT_MIN)..System.GetTime(TIME_FMT_HOUR);
seed_time_date = seed_time..System.GetDate(DATE_FMT_JULIAN);
seed_input = Math.Mod(seed_time_date, 2147483647);
Math.RandomSeed(seed_input);
result1 = Math.Random(100);
result2 = Math.Random(100);
result3 = Math.Random(100);
Debug.Print(result1 ..", "..result2..", "..result3.."\r\n");

seed_time = System.GetTime(TIME_FMT_SEC)..System.GetTime(TIME_FMT_MIN)..System.GetTime(TIME_FMT_HOUR);
seed_time_date = seed_time..System.GetDate(DATE_FMT_JULIAN);
seed_input = Math.Mod(seed_time_date, 2147483647);
Math.RandomSeed(seed_input);
result4 = Math.Random(100);
result5 = Math.Random(100);
result6 = Math.Random(100);
Debug.Print(result4 ..", "..result5..", "..result6.."\r\n");

Math.RandomSeed(5647);
result7 = Math.Random(100);
result8 = Math.Random(100);
result9 = Math.Random(100);
Debug.Print(result7 ..", "..result8..", "..result9.."\r\n");

In the first part of this example, the random number generator is seeded with the modulus of a number composed of the current seconds, minutes, hours and date (in Julian format), and the max seed number 2147483647. Using this method ensures that the seed value is always unique, resulting in a random sequence of numbers. However in the last part of the example, the seed value is always the same, therefore it's result will always be the same value.

Tip: You can copy and paste this code into the action editor to test it.


Math.Round Examples

Math.Round

number Math.Round (

number Num,

number DecimalPlaces = 0 )

Example 1

rounded = Math.Round(3.1415926535, 2);

This example rounds the number "3.1415926535" to two decimal places and stores the result in the variable "rounded". In this case, rounded will equal 3.14.

Example 2

number1 = 234;
number2 = 567;
answer = Math.Round(number1/number2, 4);

Divides two numbers, and calculates the answer, rounded to four decimal places.


Math.Sin Examples

Math.Sin

number Math.Sin (

number Num )

Example 1

sin_num = Math.Sin(1.4315);

Calculates the sine of the number 1.4315 and stores the result (0.99031394379959) in the variable "sin_num."


Math.Sqrt Examples

Math.Sqrt

number Math.Sqrt (

number Num )

Example 1

square_num = Math.Sqrt(9);

Calculates the square root of 9 and stores the result (3) in square_num.

Example 2

square_num = Math.Sqrt(45.35);

Calculates the square root of 45.35 and stores the result (6.7342408629333) in square_num.


Math.Tan Examples

Math.Tan

number Math.Tan (

number Num )

Example 1

tangent_num = Math.Tan(0.795398);

Calculates the tangent of the number 0.795398 and stores the result (1.0202023669685) in the variable "tangent_num."


MSI.ApplyPatch Examples

MSI.ApplyPatch

boolean MSI.ApplyPatch (

string PatchPath,

string InstallPackage,

number InstallType,

string CommandLine = "" )

Example 1

bPatchSuccess = MSI.ApplyPatch(_TempFolder.."\\patch.msp", "", INSTALLTYPE_DEFAULT, "REINSTALL=ALL");

if (bPatchSuccess) then
Dialog.Message("Patch Success", "The patch was applied successfully.");
else
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Uses the MSI.ApplyPatch action to search for all products on the system to apply the "patch.msp" to, and shows either a success, or error message.


MSI.CloseHandle Examples

MSI.CloseHandle

boolean MSI.CloseHandle (

number MSIHandle )

Example 1

-- Get the product handle.
nProductHandle = MSI.OpenProduct("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (nProductHandle) then
tbFeatureInfo = MSI.GetFeatureInfo(nProductHandle, "MyTargetFeature", INSTALLFEATUREATTRIBUTE_FAVORLOCAL);
if (tbFeatureInfo) then
-- Show a dialog with the feature info.
Dialog.Message("Feature Info", "Title: "..tbFeatureInfo.Title.."\r\nDescription: "..tbFeatureInfo.Description);
else
-- An error occurred.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

-- Finished using the product handle, so close it.
if (not MSI.CloseHandle(nProductHandle)) then
Dialog.Message("Error", "Failed to close product handle.");
end
else
Dialog.Message("Error", "Failed to get product handle.");
end

Gets the title and description of the "MyTargetFeature" feature and shows it in a dialog message.


MSI.ConfigureFeature Examples

MSI.ConfigureFeature

boolean MSI.ConfigureFeature (

string ProductCode,

string FeatureID,

number InstallState )

Example 1

bResult = MSI.ConfigureFeature("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "Core", INSTALLSTATE_LOCAL);

if (not bResult) then
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Configures the feature "Core" as installed locally (INSTALLSTATE_LOCAL) and shows an error dialog if the action fails.


MSI.ConfigureProduct Examples

MSI.ConfigureProduct

boolean MSI.ConfigureProduct (

string ProductCode,

number InstallLevel,

number InstallState )

Example 1

bConfigured = MSI.ConfigureProduct("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", INSTALLLEVEL_DEFAULT, INSTALLSTATE_LOCAL);

if (bConfigured) then
Dialog.Message("Configuration", "Configuration successful.");
else
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Installs the product locally on the user's system with the authored default features and shows either a success, or error message.


MSI.ConfigureProductEx Examples

MSI.ConfigureProductEx

boolean MSI.ConfigureProductEx (

string ProductCode,

number InstallLevel,

number InstallState,

string CommandLine = "" )

Example 1

bConfigured = MSI.ConfigureProductEx("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", INSTALLLEVEL_DEFAULT, INSTALLSTATE_LOCAL, "Runstate=Debug");

if (bConfigured) then
Dialog.Message("Configuration", "Configuration successful.");
else
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Installs the product locally on the user's system with the authored default features and shows either a success, or error message.


MSI.EnableLog Examples

MSI.EnableLog

boolean MSI.EnableLog (

number LogMode,

string LogFile,

boolean Append = false,

boolean FlushEachLine = false )

Example 1

MSI.EnableLog(INSTALLLOGMODE_VERBOSE, _TempFolder.."\\log.txt");

Enables verbose logging of the installation in a log file called "log.txt" created in the user's temporary directory.


MSI.EnumClients Examples

MSI.EnumClients

table MSI.EnumClients (

string ComponentGUID )

Example 1

-- Enumerate the products for the component.
tbProducts = MSI.EnumClients("{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}");

if (tbProducts) then
strMessage = "The following products were found:\r\n\r\n";
for index, value in pairs(tbProducts) do
strMessage = strMessage..value.."\r\n";
end
-- Show a message with all of the products found.
Dialog.Message("Products Found", strMessage);
else
Dialog.Message("Notice", "No products were found.");
end

Enumerates all of the clients for the installed component "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}" and shows their product codes in a dialog message. If an error occurs, or no products were found, an error message is shown.


MSI.EnumComponents Examples

MSI.EnumComponents

table MSI.EnumComponents (

)

Example 1

-- Enumerate all components.
tbComponents = MSI.EnumComponents();

if (tbComponents) then
strMessage = "The following components were found:\r\n\r\n";
for index, value in pairs(tbComponents) do
strMessage = strMessage..value.."\r\n";
end

-- Show a message with all of the components found.
Dialog.Message("Components Found", strMessage);
else
Dialog.Message("Notice", "No components were found.");
end

Gets a numerically indexed table of all installed components for all products found on the system and shows their GUIDs in a dialog message. If an error occurs, or no components were found, an error message is shown.


MSI.EnumFeatures Examples

MSI.EnumFeatures

table MSI.EnumFeatures (

string ProductCode )

Example 1

-- Enumerate the features for the product.
tbFeatures = MSI.EnumFeatures("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (tbFeatures) then
strMessage = "The following features were found:\r\n\r\n";
for index, subfeature in pairs(tbFeatures) do
strMessage = strMessage.."Feature: "..subfeature.Feature.."\r\n".."Parent Feature: "..subfeature.ParentFeature.."\r\n\r\n";
end
-- Show a message with all of the features detected.
Dialog.Message("Features Found", strMessage);
else
Dialog.Message("Notice", "No features were found.");
end

Enumerates all of the features for a given product and shows their IDs and parent IDs in a dialog message. If an error occurs, or no features were found, an error message is shown.


MSI.EnumPatches Examples

MSI.EnumPatches

table MSI.EnumPatches (

string ProductCode )

Example 1

-- Enumerate the patches for the product.
tbPatches = MSI.EnumPatches("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (tbPatches) then
strMessage = "The following patches were found:\r\n\r\n";
for index, subpatch in pairs(tbPatches) do
strMessage = strMessage.."Patch code: "..subpatch.PatchCode.."\r\n".."Transform list: "..subpatch.TransformList.."\r\n\r\n";
end
-- Show a message with all of the patches found.
Dialog.Message("Patches Found", strMessage);
else
Dialog.Message("Notice", "No patches were found.");
end

Enumerates all of the patches for a given product and shows their patch codes, and transform lists in a dialog message. If an error occurs, or no patches were found, an error message is shown.


MSI.EnumProducts Examples

MSI.EnumProducts

table MSI.EnumProducts (

)

Example 1

-- Enumerate the products.
tbProducts = MSI.EnumProducts();

if (tbProducts) then
strMessage = "The following products were detected:\r\n\r\n";
for index, value in pairs(tbProducts) do
strMessage = strMessage..value.."\r\n";
end

-- Show a message with all of the products detected.
Dialog.Message("Products Found", strMessage);
else
Dialog.Message("Notice", "No products are installed.");
end

Gets a numerically indexed table of product codes found on the system and shows them in a list in a dialog message. If an error occurs, or no products were found, an error message is shown.


MSI.EnumRelatedProducts Examples

MSI.EnumRelatedProducts

table MSI.EnumRelatedProducts (

string UpgradeCode )

Example 1

-- Enumerate the products.
tbProducts = MSI.EnumRelatedProducts("{07F11339-6660-4CEC-9E09-BB2FEA780929}");

if (tbProducts) then
strMessage = "The following products were detected for the upgrade code:\r\n\r\n";
for index, value in pairs(tbProducts) do
strMessage = strMessage..value.."\r\n";
end

-- Show a message with all of the products detected.
Dialog.Message("Products Found", strMessage);
else
Dialog.Message("Notice", "No products were found.");
end

Gets a numerically indexed table of related product codes found on the system given the upgrade code, and shows them in a list in a dialog message. If an error occurs, or no products were found, an error message is shown.


MSI.GetComponentPath Examples

MSI.GetComponentPath

table MSI.GetComponentPath (

string ProductCode,

string ComponentGUID )

Example 1

-- Get the component path.
tbComponent = MSI.GetComponentPath("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}");

-- Check if it was successful and that the component is installed locally.
if (tbComponent) then
if (tbComponent.InstallState == INSTALLSTATE_LOCAL) then
Dialog.Message("Information", "The component is installed locally.");
end
else
-- Show a message with the error.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Checks to see if the component "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}" is installed locally and shows an information message. If the action fails, an error dialog is shown.


MSI.GetFeatureInfo Examples

MSI.GetFeatureInfo

table MSI.GetFeatureInfo (

number Handle,

string FeatureID,

number Attributes )

Example 1

-- Get the product handle.
nProductHandle = MSI.OpenProduct("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (nProductHandle) then
tbFeatureInfo = MSI.GetFeatureInfo(nProductHandle, "MyTargetFeature", INSTALLFEATUREATTRIBUTE_FAVORLOCAL);
if (tbFeatureInfo) then
-- Show a dialog with the feature info.
Dialog.Message("Feature Info", "Title: "..tbFeatureInfo.Title.."\r\nDescription: "..tbFeatureInfo.Description);
else
-- An error occurred.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

-- Finished using the product handle, so close it.
if (not MSI.CloseHandle(nProductHandle)) then
Dialog.Message("Error", "Failed to close product handle.");
end
else
Dialog.Message("Error", "Failed to get product handle.");
end

Gets the title and description of the "MyTargetFeature" feature and shows it in a dialog message.


MSI.GetFeatureUsage Examples

MSI.GetFeatureUsage

table MSI.GetFeatureUsage (

string ProductCode,

string FeatureID )

Example 1

-- Get the usage metrics for the product feature.
tbFeatureMetrics = MSI.GetFeatureUsage("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "MyFeature");

-- Check if it was successful.
if (tbFeatureMetrics) then
strMessage = "The feature's usage metrics are:\r\n\r\n";
strMessage = strMessage.."Usage Count: "..tbFeatureMetrics.UsageCount.."\r\n";
strMessage = strMessage.."Day: "..tbFeatureMetrics.Day.."\r\n";
strMessage = strMessage.."Month: "..tbFeatureMetrics.Month.."\r\n";
strMessage = strMessage.."Year: "..tbFeatureMetrics.Year.."\r\n";
Dialog.Message("Feature Usage", strMessage);
else
-- Show a message with the error.
Dialog.Message("Error", "Could not get product feature usage metrics.");
end

Gets the usage metrics of a product feature with the ID "MyFeature," and shows its values in a dialog message.


MSI.GetFileVersion Examples

MSI.GetFileVersion

table MSI.GetFileVersion (

string FilePath )

Example 1

tbFileInfo = MSI.GetFileVersion(_TempFolder.."\\Extracted\\setup.exe");

if (tbFileInfo) then
Dialog.Message("File Info", "Version: "..tbFileInfo.Version.." Language: "..tbFileInfo.Language);
else
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Gets the version and language information from the file "setup.exe", and shows it in a dialog message.


MSI.GetMSIVersion Examples

MSI.GetMSIVersion

string MSI.GetMSIVersion (

)

Example 1

strVersion = MSI.GetMSIVersion();
Dialog.Message("MSI Version", "The MSI version installed is "..strVersion);

Gets the version of the Windows Installer that is installed and returns the information in a message box.

Example 2

strVersion = MSI.GetMSIVersion();

nCompare = String.CompareFileVersions(strVersion, "3.0");
if (nCompare == -1) then
Dialog.Message("Requirement Failed", "This setup requires a minimum of version 3.0 of the Windows Installer.");
end

Checks to see if the MSI version is greater than or equal to "3.0" and shows an error dialog if the condition fails.


MSI.GetPatchInfo Examples

MSI.GetPatchInfo

string MSI.GetPatchInfo (

string PatchCode,

string Attribute )

Example 1

strPatchInfo = MSI.GetPatchInfo("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "INSTALLPROPERTY_LOCALPACKAGE");

if (strPatchInfo) then
Dialog.Message("Patch Info", strPatchInfo);
else
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Gets a patch's "INSTALLPROPERTY_LOCALPACKAGE" attribute value and shows it in a dialog message.


MSI.GetProductCode Examples

MSI.GetProductCode

string MSI.GetProductCode (

string ComponentGUID )

Example 1

strProductCode = MSI.GetProductCode("{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}");

if (strProductCode ~= "") then
Dialog.Message("Information", "The product code is: "..strProductCode);
else
Dialog.Message("Error", "Error. Could not get product code.");
end

Gets the product code given the component GUID "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}" and shows it in a dialog message. If the action fails, an error dialog is shown.


MSI.GetProductInfo Examples

MSI.GetProductInfo

string MSI.GetProductInfo (

string ProductCode,

string Property )

Example 1

strVersionString = MSI.GetProductInfo("{757DCC82-E2D2-4737-95CB-E864DGH03B23}","VersionString");
Dialog.Message("Version String", strVersionString);

Gets the "VersionString" value from the product with product code "{757DCC82-E2D2-4737-95CB-E864DGH03B23}" and shows it in a dialog message.


MSI.GetProductProperty Examples

MSI.GetProductProperty

string MSI.GetProductProperty (

number Handle,

string Property )

Example 1

-- Get the product handle.
nProductHandle = MSI.OpenProduct("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (nProductHandle) then
strProperty = MSI.GetProductProperty(nProductHandle, "SUFUSERPROFILE");
if (strProperty) then
-- Show a dialog with the feature info.
Dialog.Message("Property", "Property value: "..strProperty);
else
-- An error occurred.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

-- Finished using the product handle, so close it.
if (not MSI.CloseHandle(nProductHandle)) then
Dialog.Message("Error", "Failed to close product handle.");
end
else
Dialog.Message("Error", "Failed to get product handle.");
end

Gets the product property "SUFUSERPROFILE" and shows its value in dialog message.


MSI.GetShortcutTarget Examples

MSI.GetShortcutTarget

table MSI.GetShortcutTarget (

string ShortcutTarget )

Example 1

-- Get the path to the shortcut file.
strShortcutFolder = Shell.GetFolder(SHF_DESKTOP);
strShortcutFolder = strShortcutFolder.."\\MyShortcut.lnk";

-- Get the shortcut product information.
tbShortcutInfo = MSI.GetShortcutTarget(strShortcutFolder);

-- Show the information in a dialog message.
if (tbShortcutInfo) then
strMessage = "The shortcut information is as follows:\r\n\r\n";
strMessage = strMessage.."Product Code: "..tbShortcutInfo.ProductCode.."\r\n";
strMessage = strMessage.."Feature ID: "..tbShortcutInfo.FeatureID.."\r\n";
strMessage = strMessage.."Component Code: "..tbShortcutInfo.ComponentCode.."\r\n";
Dialog.Message("Shortcut Info", strMessage);
else
-- Show an error message
Dialog.Message("Error", "Could not get shortcut info.");
end

Gets product information from a shortcut file and shows it in a dialog message, or if the action fails, an error message is shown.


MSI.GetUserInfo Examples

MSI.GetUserInfo

table MSI.GetUserInfo (

string ProductCode )

Example 1

-- Get the user info for the product.
tbUserInfo = MSIGetUserInfo("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

-- Check if it was successful.
if (tbUserInfo) then
if (tbUserInfo.UserInfoState == USERINFOSTATE_PRESENT) then
strMessage = "The product user info is as follows:\r\n\r\n";
strMessage = strMessage.."User name: "..tbUserInfo.UserName.."\r\n";
strMessage = strMessage.."Company name: "..tbUserInfo.CompanyName.."\r\n";
strMessage = strMessage.."Serial number: "..tbUserInfo.SerialNumber.."\r\n";
Dialog.Message("Product User Info", strMessage);
else
-- Show an error message
Dialog.Message("Error", "Could not get product user info.");
end
else
-- Show an error message
Dialog.Message("Error", "Could not get product user info.");
end

Gets an installed product's registered user information and shows it in a dialog message. If the information could not be queried or an error occurs, a message is shown notifying the user.


MSI.InstallMissingComponent Examples

MSI.InstallMissingComponent

boolean MSI.InstallMissingComponent (

string ProductCode,

string ComponentGUID,

number InstallState )

Example 1

bResult = MSI.InstallMissingComponent("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}", INSTALLSTATE_LOCAL);

if (not bResult) then
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Installs the missing component "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}" locally (INSTALLSTATE_LOCAL) and shows an error dialog if the action fails.


MSI.InstallMissingFile Examples

MSI.InstallMissingFile

boolean MSI.InstallMissingFile (

string ProductCode,

string File )

Example 1

bResult = MSI.InstallMissingFile("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "myfile.txt");

if (not bResult) then
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Installs the missing file "myfile.txt" and shows an error dialog if the action fails.


MSI.InstallProduct Examples

MSI.InstallProduct

boolean MSI.InstallProduct (

string PackagePath,

string CommandLine)

Example 1

bInstalled = MSI.InstallProduct(_TempFolder.."\\TempMSI\\setup.msi","REMOVE=ALL");

if (not bInstalled) then
nInstallError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nInstallError], MB_OK, MB_ICONEXCLAMATION);
end

Calls "setup.msi" to uninstall the current copy of the product.


MSI.LocateComponent Examples

MSI.LocateComponent

table MSI.LocateComponent (

string ComponentGUID )

Example 1

-- Get the component path.
tbComponent = MSI.LocateComponent("{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}");

-- Check if it was successful and that the component is installed locally.
if (tbComponent) then
if (tbComponent.InstallState == INSTALLSTATE_LOCAL) then
Dialog.Message("Information", "The component is installed locally.");
end
else
-- Show a message with the error.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Checks to see if the component with GUID "{1638E94C-DA3C-44BD-88FB-5CC76B59BE46}" is installed locally and shows an information message. If the action fails, an error dialog is shown.


MSI.OpenPackage Examples

MSI.OpenPackage

number MSI.OpenPackage (

string PackagePath )

Example 1

-- Get the package handle.
nPackageHandle = MSI.OpenPackage(_TempFolder.."\\Downloaded\\setup.msi");

if (nPackageHandle ) then
strProperty = MSI.GetProductProperty(nPackageHandle, "SUFUSERPROFILE");
if (strProperty) then
-- Show a dialog with the feature info.
Dialog.Message("Property", "Property value: "..strProperty);
else
-- An error occurred.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

-- Finished using the handle, so close it.
if (not MSI.CloseHandle(nPackageHandle)) then
Dialog.Message("Error", "Failed to close package handle.");
end
else
Dialog.Message("Error", "Failed to get package handle.");
end

Gets the product property "SUFUSERPROFILE" and shows its value in dialog message.


MSI.OpenProduct Examples

MSI.OpenProduct

number MSI.OpenProduct (

string ProductCode )

Example 1

-- Get the product handle.
nProductHandle = MSI.OpenProduct("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (nProductHandle) then
tbFeatureInfo = MSI.GetFeatureInfo(nProductHandle, "MyTargetFeature", INSTALLFEATUREATTRIBUTE_FAVORLOCAL);
if (tbFeatureInfo) then
-- Show a dialog with the feature info.
Dialog.Message("Feature Info", "Title: "..tbFeatureInfo.Title.."\r\nDescription: "..tbFeatureInfo.Description);
else
-- An error occurred.
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

-- Finished using the product handle, so close it.
if (not MSI.CloseHandle(nProductHandle)) then
Dialog.Message("Error", "Failed to close product handle.");
end
else
Dialog.Message("Error", "Failed to get product handle.");
end

Gets the title and description of the "MyTargetFeature" feature and shows it in a dialog message.


MSI.QueryFeatureState Examples

MSI.QueryFeatureState

number MSI.QueryFeatureState (

string ProductCode,

string Feature )

Example 1

-- Get the feature state.
nFeatureState = MSI.QueryFeatureState("{C0805078-0A3E-44AE-A696-56088114D161}", "Complete");

if (nFeatureState == INSTALLSTATE_LOCAL) then
Dialog.Message("Feature Installed", "The feature is installed locally.");
else
Dialog.Message("Feature State", "The feature query returned value: "..nFeatureState);
end

Gets the feature state of the "Complete" feature of the product with code "{C0805078-0A3E-44AE-A696-56088114D161}"


MSI.QueryProductState Examples

MSI.QueryProductState

number MSI.QueryProductState (

string ProductCode )

Example 1

-- Get the product's installed state.
nState = MSI.QueryProductState("{78B82B0B-9AD9-40C0-B994-F72C21B52723}");

if (INSTALLSTATE_DEFAULT == nState) then
Dialog.Message("Installed State", "The product is installed for the current user.");
else
Dialog.Message("State Unknown", "The product is either not installed, or an error occurred.");
end

Determines whether or not a product with the product code "{78B82B0B-9AD9-40C0-B994-F72C21B52723}" is installed for the current user showing the result in a dialog message.


MSI.ReinstallFeature Examples

MSI.ReinstallFeature

boolean MSI.ReinstallFeature (

string ProductCode,

string FeatureID,

number ReinstallMode )

Example 1

bResult = MSI.ReinstallFeature("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", "Core", REINSTALLMODE_FILEMISSING);

if (not bResult) then
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Reinstalls the feature "Core" if the file is missing and shows an error dialog if the action fails.


MSI.ReinstallProduct Examples

MSI.ReinstallProduct

boolean MSI.ReinstallProduct (

string ProductCode,

number ReinstallMode )

Example 1

bResult = MSI.ReinstallProduct("{78B82B0B-9AD9-40C0-B994-F72C21B52723}", REINSTALLMODE_FILEMISSING);

if (not bResult) then
nError = Application.GetLastError();
Dialog.Message("Error", _tblErrorMessages[nError], MB_OK, MB_ICONEXCLAMATION);
end

Reinstalls the product if the file is missing and shows an error dialog if the action fails.


MSI.RunMsiexec Examples

MSI.RunMsiexec

number MSI.RunMsiexec (

string Arguments,

boolean WaitForReturn = true )

Example 1

-- The path to extract the file.
strExtractPath = Shell.GetFolder(SHF_APPLICATIONDATA).."\\ExtractedInstallation\\setup.msi";

strCommandLine = "-i \""..strExtractPath.."\" REINSTALL=ALL REINSTALLMODE=vomus";
-- Run the setup.
nResult = MSI.RunMsiexec(strCommandLine);

Runs the file "setup.msi" using the MSI.RunMsiexec action.


MSI.SetInternalUI Examples

MSI.SetInternalUI

table MSI.SetInternalUI (

number UILevel,

number WindowHandle = nil )

Example 1

-- Create unique extract path using a previously defined function.
strInstallerPathExtracted = g_CreateExtractPath(strProductCode);

local tbResult = MSI.SetInternalUI(INSTALLUILEVEL_FULL);

if (not tbResult) then
Dialog.Message("Error", "Failed MSI.SetInternalUI");
end

MSI.InstallProduct(strInstallerPathExtracted,"");

Calls MSI.SetInternalUI to display the full internal interface. If the call fails, an error message is shown to the user. The MSI file is then installed.


MSI.VerifyPackage Examples

MSI.VerifyPackage

boolean MSI.VerifyPackage (

string PackagePath )

Example 1

bResult = MSI.VerifyPackage(_TempFolder.."\\setup.msi");

if (bResult) then
Dialog.Message("Is Package", "Yes, the file is a package.");
else
Dialog.Message("Not Package", "The file is not a package, or an error was encountered.");
end

Checks to see if the file "setup.msi" in the user's temporary folder is an installation package and shows the result in a dialog message.


ODBC.ConfigDataSource Examples

ODBC.ConfigDataSource

ODBC.ConfigDataSource (

string DriverDescription,

string Attributes,

number Request )

Example 1

ODBC.ConfigDataSource("Microsoft Access Driver (*.mdb)", "DSN=QandA\\0DBQ=J:\\DATABASE\\QandA.mdb\\0FIL=MS Access;\\0DESCRIPTION=Questions and Answers Database\\0DRIVERID=25\\0UID=\\0\\0", ODBC_ADD_SYS_DSN);

Adds a new system data source to the Microsoft Access Driver ODBC driver.


ODBC.InstallDriver Examples

ODBC.InstallDriver

string ODBC.InstallDriver (

string Driver )

Example 1

strResult = ODBC.InstallDriver("Microsoft Access Driver(*.mdb)\\0Driver=odbcjt32.dll\\0Setup=odbcjt32.dll\\0FileUsage=1\\0FileExtns=*.mdb\\0APILevel=1\\0ConnectFunctions=YYN\\0DriverODBCVer=02.50\\0SQLLevel=0\\0\\0");

if strResult == "" then
Dialog.Message("ERROR", "The driver was not installed");
else
Dialog.Message("SUCCESS", "The driver was installed to " .. strResult .. ".");
end

Installs the Microsoft Access ODBC driver to the user's system.


ODBC.InstallManager Examples

ODBC.InstallManager

string ODBC.InstallManager (

)

Example 1

strResult = ODBC.InstallManager();

if strResult == "" then
Dialog.Message("ERROR", "There was an error. The manager was not installed.");
else
Dialog.Message("SUCCESS", "The ODBC manager's path is " .. strResult .. ".");
end

Installs the ODBC manager to the user's system.


ODBC.UninstallDriver Examples

ODBC.UninstallDriver

number ODBC.UninstallDriver (

string Driver,

boolean RemoveDSN = false )

Example 1

UsageCount = ODBC.UninstallDriver("Microsoft Access Driver (*.mdb)", false);

Removes the Microsoft Access ODBC driver, and stores the resulting usage count in variable 'UsageCount'.

Example 2

ODBC.UninstallDriver("Microsoft Access Driver (*.mdb)", true);

Removes the Microsoft Access ODBC Driver, and all DSN's associated with the driver.


ODBC.UninstallManager Examples

ODBC.UninstallManager

number ODBC.UninstallManager (

)

Example 1

UsageCount = ODBC.UninstallManager();

Uninstalls the ODBC manager, and stores the modified usage count in variable 'UsageCount'.


Registry.CreateKey Examples

Registry.CreateKey

Registry.CreateKey (

number MainKey,

string SubKey )

Example 1

Registry.CreateKey (HKEY_LOCAL_MACHINE, "Software\\My Application");

Creates the sub key "My Application" in HKEY_LOCAL_MACHINE\Software.

Example 2

Registry.CreateKey (2, "Software\\My Application");

Creates the sub key "My Application" in HKEY_CURRENT_USER\Software.


Registry.DeleteKey Examples

Registry.DeleteKey

Registry.DeleteKey (

number MainKey,

string SubKey )

Example 1

Registry.DeleteKey (HKEY_LOCAL_MACHINE, "Software\\My Application");

Deletes the sub key "My Application" from HKEY_LOCAL_MACHINE\Software.

Example 2

Registry.DeleteKey (2, "Software\\My Application");

Deletes the sub key "My Application" from HKEY_CURRENT_USER\Software.


Registry.DeleteValue Examples

Registry.DeleteValue

Registry.DeleteValue (

number MainKey,

string SubKey,

string Value )

Example 1

Registry.DeleteValue (HKEY_LOCAL_MACHINE, "Software\\My Application", "InstallPath");

Deletes the value "InstallPath" from the sub key HKEY_LOCAL_MACHINE\Software\My Application.

Example 2

Registry.DeleteValue (2, "Software\\My Application", "InstallPath");

Deletes the value "InstallPath" from the sub key HKEY_CURRENT_USER\Software\My Application.


Registry.DoesKeyExist Examples

Registry.DoesKeyExist

boolean Registry.DoesKeyExist (

number MainKey,

string SubKey )

Example 1

is_there = Registry.DoesKeyExist (HKEY_LOCAL_MACHINE, "Software\\My Application");

Checks to see if the key "My Application" exists in HKEY_LOCAL_MACHINE\Software and returns either true or false in the variable "is_there."


Registry.GetAccess Examples

Registry.GetAccess

boolean Registry.GetAccess (

number MainKey,

string SubKey,

number Rights = ACCESS_ALL )

Example 1

access = Registry.GetAccess (HKEY_LOCAL_MACHINE, "Software\\My Application", ACCESS_WRITE);

Checks to see if the key "HKEY_LOCAL_MACHINE\Software\My Application" has write access and returns either true or false in the variable "access."


Registry.GetKeyNames Examples

Registry.GetKeyNames

table Registry.GetKeyNames (

number MainKey,

string SubKey )

Example 1

all_names = Registry.GetKeyNames (HKEY_LOCAL_MACHINE, "Software\\My Application");

Gets the names of all of the sub keys under "HKEY_LOCAL_MACHINE\Software\My Application" and stores them in a table called "all_names."


Registry.GetValue Examples

Registry.GetValue

string Registry.GetValue (

number MainKey,

string SubKey,

string Value,

boolean AutoExpand = true )

Example 1

reg_data = Registry.GetValue(HKEY_LOCAL_MACHINE, "Software\\My Application", "InstallPath", false);

Gets the data in the "InstallPath" value found in "HKEY_LOCAL_MACHINE\Software\My Application" and stores it in a variable called "reg_data."

Example 2

-- Set the data "Saved Value" in the user's Registry.
Registry.SetValue(HKEY_CURRENT_USER, "Software\\My Application", "MyValue", "Saved Value", REG_SZ);

-- Read the previously written value.
registry_value = Registry.GetValue(HKEY_CURRENT_USER, "Software\\My Application", "MyValue", true);

-- Display the value read from the Registry in a dialog.
Dialog.Message("Registry Data", "The value read from the Registry is "..registry_value..".");

Sets the "MyValue" value's data to the string "Saved Value". The value is located in "HKEY_CURRENT_USER\Software\My Application" and will have a value of REG_SZ. That value is then read back and displayed in a dialog.

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files folder.

Example 3

-- Add a value to the registry.
Registry.SetValue(HKEY_CURRENT_USER, "Software\\My_Application", "User_Temp", "%Temp%", REG_EXPAND_SZ);

-- Get the unexpanded and expanded values.
sRaw = Registry.GetValue(HKEY_CURRENT_USER, "Software\\My_Application", "User_Temp", false);
sExpanded = Registry.GetValue(HKEY_CURRENT_USER, "Software\\My_Application", "User_Temp", true);

-- Output retrieved data to the user.
Dialog.Message("Temporary Directory", "Raw Data: " .. sRaw .. "\r\n" .. "Expanded Data: " .. sExpanded);

Adds the windows environment variable %Temp% to the registry as a REG_EXPAND_SZ value. Retrieves both the unexpanded and expanded contents of this registry value and outputs them to the user.


Registry.GetValueNames Examples

Registry.GetValueNames

table Registry.GetValueNames (

number MainKey,

string SubKey )

Example 1

value_names = Registry.GetValueNames(HKEY_LOCAL_MACHINE, "Software\\My Application");

Gets all the value names within the sub key "HKEY_LOCAL_MACHINE\Software\My Application" and stores them in a table called "value_names."


Registry.GetValueType Examples

Registry.GetValueType

number Registry.GetValueType (

number MainKey,

string SubKey,

string Value )

Example 1

value_type = Registry.GetValueType (HKEY_LOCAL_MACHINE, "Software\\My Application", "InstallPath");

Gets the type of data stored in the "InstallPath" value located at "HKEY_LOCAL_MACHINE\Software\My Application" and stores the corresponding numeric constant in value_type. If the "InstallPath" value was of type REG_SZ, the number 1 would be returned.

You could test the return value with an if statement, like this:

if value_type == REG_SZ then

-- only do this part if the InstallPath Registry value
-- at HKEY_LOCAL_MACHINE\Software\My Application
-- is of type REG_SZ (a string)

end


Registry.SetValue Examples

Registry.SetValue

Registry.SetValue (

number MainKey,

string SubKey,

string Value,

string Data,

number Type = REG_SZ )

Example 1

Registry.SetValue (HKEY_LOCAL_MACHINE, "Software\\My Application", "InstallPath", _ProgramFilesFolder .. "\\My Application", 1);

Sets the "InstallPath" value's data to the "My Application" folder's path located in the user's Program Files directory (normally C:\ProgramFiles\My Application). The value is located in "HKEY_LOCAL_MACHINE\Software\My Application" and will have a value of REG_SZ.

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files folder.

Example 2

-- Set the data "Saved Value" in the user's Registry.
Registry.SetValue(HKEY_CURRENT_USER, "Software\\My Application", "MyValue", "Saved Value", REG_SZ);

-- Read the previously written value.
registry_value = Registry.GetValue(HKEY_CURRENT_USER, "Software\\My Application", "MyValue", true);

-- Display the value read from the Registry in a dialog.
Dialog.Message("Registry Data", "The value read from the Registry is "..registry_value..".");

Sets the "MyValue" value's data to the string "Saved Value". The value is located in "HKEY_CURRENT_USER\Software\My Application" and will have a value of REG_SZ. That value is then read back and displayed in a dialog.

Note: _ProgramFilesFolder is a built-in variable that contains the path to the user's Program Files folder.


Screen.Back Examples

Screen.Back

Screen.Back (

)

Example 1

Screen.Back();

Moves back one screen in the history of the viewed screens.


Screen.End Examples

Screen.End

Screen.End (

)

Example 1

Screen.End();

Jumps to the end of the current screen list and starts the next stage in the install.


Screen.GetFocus Examples

Screen.GetFocus

number Screen.GetFocus (

)

Example 1

nControlID = Screen.GetFocus();

Gets the control id of the object which currently has focus.


Screen.GetLocalizedString Examples

Screen.GetLocalizedString

string Screen.GetLocalizedString (

string StringID )

Example 1

sLocalString = Screen.GetLocalizedString("My_String_ID");

Gets the localized text for the string with ID "My_String_ID" and stores it in the variable "sLocalString."

Example 2

Localized = Screen.GetLocalizedString(sMsgID);

Gets the localized text for the string with ID referenced in the variable "sMsgID" and stores it in the variable "Localized".


Screen.GetProperties Example

Screen.GetProperties

table Screen.GetProperties (

)

Example 1

tScreenProperties = Screen.GetProperties();

Gets the properties from the current screen and stores them in table "tScreenProperties".

Example 2

-- Initialize nButtons to zero
nButtons = 0;

-- Get the screen properties
tProps = Screen.GetProperties();

-- Traverse through the table, looking for buttons.
-- When one is found, add one to nButtons
for nIndex, Data in pairs(tProps.Controls) do
if Data.Type == 1 then
-- Item is a button
nButtons = nButtons + 1;
end
end

-- Output the button count to the user
Dialog.Message("Button Count", "There are " .. nButtons .. " buttons on this screen.");

Retrieves the properties from the current screen, stores them in table "tProps", and counts the number of buttons on the current screen. The result is displayed to the user as a message dialog.


Screen.Jump Examples

Screen.Jump

Screen.Jump (

string ScreenName )

Example 1

Screen.Jump("Welcome To Install");

Jumps to the screen named "Welcome To Install."

Example 2

Screen.Jump(sScreenName);

Jumps to the screen who's name is contained in the variable "sScreenName."


Screen.Next Examples

Screen.Next

Screen.Next (

)

Example 1

Screen.Next();

Proceeds to the next screen.


Screen.Previous Examples

Screen.Previous

Screen.Previous (

)

Example 1

Screen.Previous();

Proceeds to the previous screen in your setup.


Screen.SetFocus Examples

Screen.SetFocus

Screen.SetFocus (

number ControlID )

Example 1

Screen.SetFocus (CTRL_EDIT_01);

Gives focus to the edit field control with control ID CTRL_EDIT_01.

Example 2

Screen.SetFocus (nControlID);

Gives focus to the control who's control ID is referenced in variable "nControlID".


Screen.SetLocalizedString Examples

Screen.SetLocalizedString

Screen.SetLocalizedString (

string StringID,

string Text )

Example 1

Screen.SetLocalizedString("My_String", "Hello, thank-you for installing this!");

Sets the string with id "My_String" to "Hello, thank-you for installing this!" for the current screen.

Example 2

Screen.SetLocalizedString(sStringID, sString);

Sets the string with the id referenced in "sStringID" to the string referenced in "sString" for the current screen.


Screen.SetStartScreen Examples

Screen.SetStartScreen

Screen.SetStartScreen (

string ScreenName )

Example 1

-- Get the operating system's version info.
tbVersionInfo = System.GetOSVersionInfo();

-- Check to make sure the version info was received successfully.
if (tbVersionInfo) then
-- Check to see if the system is a server system.
if (tbVersionInfo.ProductType == 3) then
-- Set the start screen to the Server type block of screens.
Screen.SetStartScreen("Server Welcome");
end
end

Checks to see if the target system is a type of server operating system and if so, sets the screens to start at the block designed for servers.


Screen.StartTimer Examples

Screen.StartTimer

Screen.StartTimer ( number Interval

)

Example 1

Screen.StartTimer(1500);

Starts a timer on the current screen and sets it to fire once every 1.5 seconds.

Example 2

Screen.StartTimer(nTimerInterval);

Starts a timer on the current screen and sets it to fire at the interval specified in the variable 'nTimerInterval'.


Screen.StopTimer Examples

Screen.StopTimer

Screen.StopTimer (

)

Example 1

Screen.StopTimer();

Stops the timer on the current page.


Service.Continue Examples

Service.Continue

Service.Continue (

string DisplayName,

string KeyName = "" )

Example 1

Service.Continue("Service1", "");

Continues the service "Service1".

Example 2

-- Specify the antivirus service display name
VirusScannerServiceName = "AntiVirus";

-- Pause the virus scanner
Service.Pause(VirusScannerServiceName, "");

-- Run the setup which cannot be run while a virus scanner is active
File.Run(SessionVar.Expand("%SourceFolder%\\setup2.exe"), "", "", SW_SHOWNORMAL, true);

-- Resume the virus scanner
Service.Continue(VirusScannerServiceName, "");

Pauses the specified virus scanner service before launching a separate setup file.

Example 3

-- Specify the service to query
ServiceToQueryDisplay = "Service1";
ServiceToQueryKey = "Boom";

-- Query the specified service
QueryResult = Service.Query(ServiceToQueryDisplay, ServiceToQueryKey);
if not (QueryResult == SERVICE_RUNNING) then
-- Set err to 0
err = 0;
-- The service is not running.
if (QueryResult == SERVICE_PAUSED) then
-- The service is paused, try continue
Service.Continue(ServiceToQueryDisplay, ServiceToQueryKey);
err = Application.GetLastError();
elseif (QueryResult == SERVICE_STOPPED) then
-- The service is stopped, try start
Service.Start(ServiceToQueryDisplay, ServiceToQueryKey, nil);
err = Application.GetLastError();
end
if not (err == 0) then
-- An error happened with Continue/Start
Dialog.Message("Error (" .. err .. ")", "Unable to start/restart the service.\r\nService is not running");
else
Dialog.Message("PERFECTION!", "The service was started/restarted fine.");
end
else
-- The service is running
Dialog.Message("PERFECTION!", "The service is running fine.");
end

Queries the specified service. If it is running, a dialog is displayed. If it is not running, it is restarted and either a successful or error dialog is displayed.


Service.Create Examples

Service.Create

Service.Create (

string Filename,

string DisplayName = "Service1",

string KeyName = "",

number ServiceType = SERVICE_WIN32_OWN_PROCESS,

boolean AllowDesktopInteraction = false,

number StartType = SERVICE_DEMAND_START,

number ErrorControl = SERVICE_ERROR_NORMAL,

string LoadOrderGroup = "",

number GroupTag = nil,

table Dependencies = nil,

string ServiceStartName = "",

string Password = "" )

Example 1

-- Create a Service1.exe service
Service.Create("C:\\WINDOWS\\Service1.exe", "Service1", "Service1", SERVICE_WIN32_OWN_PROCESS, true, SERVICE_DEMAND_START, SERVICE_ERROR_NORMAL, "", "", nil, "", "");

-- Get the last error (0 == success)
err = Application.GetLastError();

if err ~= 0 then
-- If there was an error, output to user
Dialog.Message(err, _tblErrorMessages[err]);
end

Creates a service named Service1 using Service1.exe from C:\WINDOWS.


Service.Delete Examples

Service.Delete

Service.Delete (

string DisplayName,

string KeyName = "" )

Example 1

Service.Delete("Service1", "Service1");

Removes 'Service1' from the user's system.


Service.Pause Examples

Service.Pause

Service.Pause (

string DisplayName,

string KeyName = "" )

Example 1

Service.Pause("Service1", "");

Pauses the service "Service1".

Example 2

-- Specify the antivirus service display name
VirusScannerServiceName = "AntiVirus";

-- Pause the virus scanner
Service.Pause(VirusScannerServiceName, "");

-- Run the setup which cannot be run while a virus scanner is active
File.Run(SessionVar.Expand("%SourceFolder%\\setup2.exe"), "", "", SW_SHOWNORMAL, true);

-- Resume the virus scanner
Service.Continue(VirusScannerServiceName, "");

Pauses the specified virus scanner service before launching a separate setup file.


Service.Query Examples

Service.Query

number Service.Query (

string DisplayName,

string KeyName = "" )

Example 1

result = Service.Query("Service1", "");

Queries the service with display name 'Service1' and stores the result in variable 'result'.

Example 2

-- Specify the service to query
ServiceToQueryDisplay = "Service1";
ServiceToQueryKey = "Boom";

-- Query the specified service
QueryResult = Service.Query(ServiceToQueryDisplay, ServiceToQueryKey);
if not (QueryResult == SERVICE_RUNNING) then
-- Set err to 0
err = 0;
-- The service is not running.
if (QueryResult == SERVICE_PAUSED) then
-- The service is paused, try continue
Service.Continue(ServiceToQueryDisplay, ServiceToQueryKey);
err = Application.GetLastError();
elseif (QueryResult == SERVICE_STOPPED) then
-- The service is stopped, try start
Service.Start(ServiceToQueryDisplay, ServiceToQueryKey, nil);
err = Application.GetLastError();
end
if not (err == 0) then
-- An error happened with Continue/Start
Dialog.Message("Error (" .. err .. ")", "Unable to start/restart the service.\r\nService is not running");
else
Dialog.Message("PERFECTION!", "The service was started/restarted fine.");
end
else
-- The service is running
Dialog.Message("PERFECTION!", "The service is running fine.");
end

Queries the specified service. If it is running, a dialog is displayed. If it is not running, it is restarted and either a successful or error dialog is displayed.


Service.Start Examples

Service.Start

Service.Start (

string DisplayName,

string KeyName = "",

table Arguments = nil )

Example 1

Service.Start("StartMe", "", nil);

Starts the service "StartMe".

Example 2

-- specify the service's display name and location
ServiceDisplayName = "Service1";
ServiceFilePath = "C:\\WINDOWS\\SERVICE1.EXE";

-- Stop the specified service
Service.Stop(ServiceDisplayName, "");

-- Copy the replacement service exe
File.Copy(SessionVar.Expand("%SourceFolder%\\SERVICES\\SERVICE1.EX_"), ServiceFilePath, false, true, false, true, nil);

-- Start the service
Service.Start(ServiceDisplayName, "", nil);

Stops the specified service, replaces the exe file, and starts the service.

Example 3

-- Specify the service to query
ServiceToQueryDisplay = "Service1";
ServiceToQueryKey = "Boom";

-- Query the specified service
QueryResult = Service.Query(ServiceToQueryDisplay, ServiceToQueryKey);
if not (QueryResult == SERVICE_RUNNING) then
-- Set err to 0
err = 0;
-- The service is not running.
if (QueryResult == SERVICE_PAUSED) then
-- The service is paused, try continue
Service.Continue(ServiceToQueryDisplay, ServiceToQueryKey);
err = Application.GetLastError();
elseif (QueryResult == SERVICE_STOPPED) then
-- The service is stopped, try start
Service.Start(ServiceToQueryDisplay, ServiceToQueryKey, nil);
err = Application.GetLastError();
end
if not (err == 0) then
-- An error happened with Continue/Start
Dialog.Message("Error (" .. err .. ")", "Unable to start/restart the service.\r\nService is not running");
else
Dialog.Message("PERFECTION!", "The service was started/restarted fine.");
end
else
-- The service is running
Dialog.Message("PERFECTION!", "The service is running fine.");
end

Queries the specified service. If it is running, a dialog is displayed. If it is not running, it is restarted and either a successful or error dialog is displayed.


Service.Stop Examples

Service.Stop

Service.Stop (

string DisplayName,

string KeyName = "",

number WaitTime = 0 )

Example 1

Service.Stop ("Freeze", "");

Stops the service "Freeze".

Example 2

-- specify the service's display name and location
ServiceDisplayName = "Service1";
ServiceFilePath = "C:\\WINDOWS\\SERVICE1.EXE";

-- Stop the specified service
Service.Stop(ServiceDisplayName, "", 5);

-- Copy the replacement service exe
File.Copy(SessionVar.Expand("%SourceFolder%\\SERVICES\\SERVICE1.EX_"), ServiceFilePath, false, true, false, true, nil);

-- Start the service
Service.Start(ServiceDisplayName, "", nil);

Stops the specified service, replaces the exe file, and starts the service.


SessionVar.Expand Examples

SessionVar.Expand

string SessionVar.Expand (

string Text )

Example 1

sProductName = SessionVar.Expand("%ProductName%");

Gets the product name from the session variable %ProductName% and stores it in a string "sProductName."

Example 2

sInstallMessage = SessionVar.Expand("%ProductName% v%ProductVer% Setup");

Stores a custom install message in a string "sInstallMessage" from the session variables %ProductName% and %ProductVer%.


SessionVar.Get Examples

SessionVar.Get

string SessionVar.Get (

string VariableName )

Example 1

sAppFolder = SessionVar.Get("%AppFolder%");

Gets the contents of the session variable %AppFolder%. If %AppFolder% contains other session variables (by default %ProgramFilesFolder% and %ProductName%), these variable names will be returned.

Example 2

sResult = SessionVar.Get(sVarName);

Gets the contents of the session variable contained in "sVarName". If this variable contains other session variables, these variable names will be returned.


SessionVar.Remove Examples

SessionVar.Remove

SessionVar.Remove (

string VariableName )

Example 1

SessionVar.Remove("%UserSerialNumber%");

Undefines the session variable %UserSerialNumber%.

Example 2

sVariableName = "%Password%";
SessionVar.Remove(sVariableName);

Undefines the session variable %Password%, which is stored in the string "sVariableName."


SessionVar.Set Examples

SessionVar.Set

SessionVar.Set (

string VariableName,

string Value )

Example 1

SessionVar.Set("%ReleaseDate%", "January 1");

Sets the value of %ReleaseDate% to "January 1". If %ReleaseDate% does not exist, it is created.

Example 2

SessionVar.Set("%InstallDate%", System.GetDate(DATE_FMT_JULIAN));

Sets the value of %InstallDate% to the current date, in Julian format.


SetupData.CalculateRequiredSpace Examples

SetupData.CalculateRequiredSpace

number SetupData.CalculateRequiredSpace (

function CallbackFunction = nil )

Example 1

Req_Space = SetupData.CalculateRequiredSpace(nil);

Calculates the disk space required by the install and stores the value in "Req_Space."

Example 2

-- Callback function for action SetupData.CalculateRequiredSpace()
function Callback (sName, nPercent)
-- Set title, message, statustext, hide the progress meter and show the cancel button.
StatusDlg.SetTitle("Calculating Space Required . . . ");
StatusDlg.SetMessage("Please wait . . . " .. nPercent .. "% Complete");
StatusDlg.ShowProgressMeter(false);
--StatusDlg.ShowCancelButton(true, "Abort");
-- Check if the cancel button was pressed
bCancel = StatusDlg.IsCancelled();
-- Let the action continue to the next file
return true;
end

-- Show the status dialog
StatusDlg.Show(0, false);

-- Calculate the space required
nSpaceRequired = SetupData.CalculateRequiredSpace(Callback);

-- Report the results to the user
Dialog.Message("Space Required", String.GetFormattedSize(nSpaceRequired, FMTSIZE_AUTOMATIC, true));

-- Hide the status dialog
StatusDlg.Hide();

Calculates the amount of disk space required on the user's system and displays the formatted results to the user. The callback function is used to provide the user with a custom status display while calculating.


SetupData.GetAppShortcutFolderPath Examples

SetupData.GetAppShortcutFolderPath

string SetupData.GetAppShortcutFolderPath (

)

Example 1

sPath = SetupData.GetAppShortcutFolderPath();

Gets the path to the folder where shortcuts are being installed by the setup and stores this path in "sPath."


SetupData.GetFileList Examples

SetupData.GetFileList

table SetupData.GetFileList (

number ListToGet = ARCHIVE_LIST )

Example 1

tFiles = SetupData.GetFileList(ARCHIVE_LIST);

Gets the list of archive files (and corresponding properties) from the installation, and stores them in table "tFiles".

Example 2

-- Function to convert any boolean values to strings
function BoolToString(value)
if type (value) == "boolean" then
if value then
return "True";
else
return "False";
end
else
return value;
end
end

-- Get the list of files and properties
tFileList = SetupData.GetFileList(BOTH_LISTS);

-- Initialize variable to hold information
StringToWrite = "";

-- Traverse through each file in the table
for nIndex, PropTable in pairs(tFileList) do

-- Get filename and write it to the string
StringToWrite = StringToWrite .. "#########################################" .. "\r\n";
StringToWrite = StringToWrite .. "Filename: " .. PropTable.FileName .. "\r\n\r\n";

-- Traverse through property table
for sSubIndex, Value in pairs(PropTable) do
-- If the current property is not the filename, and is not a table, store in string
if sSubIndex ~= "FileName" and type(Value) ~= "table" then
StringToWrite = StringToWrite .. sSubIndex .. ": " .. BoolToString(Value) .. "\r\n";

-- If the current property is packages, traverse the table and store in string
elseif sSubIndex == "Packages" and Value then
StringToWrite = StringToWrite .. sSubIndex .. ": ..." .. "\r\n";

for nPackageIndex, sPackageName in pairs(Value) do
StringToWrite = StringToWrite .. " [PACKAGE " .. nPackageIndex .. "] " .. sPackageName .. "\r\n";
end

end

end

-- Finish off current filename in string with a nice 'footer'
StringToWrite = StringToWrite .. "#########################################" .. "\r\n\r\n\r\n";

end

-- Write string to a file
TextFile.WriteFromString("C:\\Project_File_Report.txt", StringToWrite, false);

Gets the list of files from the setup, and outputs it (and corresponding properties) to "C:\Project_File_Report.txt".


SetupData.GetLocalizedString Examples

SetupData.GetLocalizedString

string SetupData.GetLocalizedString (

string StringID )

Example 1

sLocalSuccess = SetupData.GetLocalizedString("MSG_SUCCESS");

Gets the localized "success" string and stores it in string sLocalSuccess.


SetupData.GetPackageList Examples

SetupData.GetPackageList

table SetupData.GetPackageList (

)

Example 1

packages = SetupData.GetPackageList();

Gets the packages available in the current install and stores them in table 'packages'.

Example 2

tPackageList = SetupData.GetPackageList();

if tPackageList then
sMessage = "Packages available in this install:" .. "\r\n";
for nIndex, sName in pairs(tPackageList) do
sMessage = sMessage .. sName .. "\r\n";
end
else
sMessage = "There are no packages available in this install.";
end

Dialog.Message("Packages Available", sMessage);

Gets the packages available in the current install, stores them in table 'tPackageList', and outputs them to the user. If there are no packages available in the current install, the user is informed.


SetupData.GetPackageProperties Examples

SetupData.GetPackageProperties

table SetupData.GetPackageProperties (

string PackageName )

Example 1

tProp = SetupData.GetPackageProperties("Default");

Gets the package properties for the package named "Default" and stores them in table "tProp".

Example 2

sPackageDescription = SetupData.GetPackageProperties(sPackageName).Description;

Gets the package description for the package name stored in string "sPackageName" and stores it in string "sPackageDescription".


SetupData.GetSerialListNames Examples

SetupData.GetSerialListNames

table SetupData.GetSerialListNames (

)

Example 1

tSerialLists = SetupData.GetSerialListNames();

Gets the names of all of the serial number lists and stores them in the table "tSerialLists."

Example 2

- Get the list names and set serial number to search for
tListNames = SetupData.GetSerialListNames();
sSerialToCheck = "ABCD-1234-DCBA-4321";

-- assume the serial number is not valid
bIsValid = false;

-- Traverse through the name table
for nIndex, sName in pairs(tListNames) do
-- check if given serial is valid in current list
bIsValid = SetupData.IsValidSerialNumber(sName, sSerialToCheck)
if bIsValid then
-- the serial is valid, break out of the loop
break;
end
end

if bIsValid then
-- The serial number exists in at least one of the lists
Dialog.Message("", "YAY");
else
-- The serial number does not exist in any of the lists
Dialog.Message("", "NAY");
end

Checks if a given serial number is valid in any of the lists in the installer.


SetupData.IsValidSerialNumber Examples

SetupData.IsValidSerialNumber

boolean SetupData.IsValidSerialNumber (

string ListName,

string SerialNumber )

Example 1

bValid = SetupData.IsValidSerialNumber("List 1", strSerial);

Checks if a specified serial stored in string "strSerial" is valid in "List 1"

Example 2

-- Get the list names and set serial number to search for
tListNames = SetupData.GetSerialListNames();
sSerialToCheck = "ABCD-1234-DCBA-4321";

-- assume the serial number is not valid
bIsValid = false;

-- Traverse through the name table
for nIndex, sName in pairs(tListNames) do
-- check if given serial is valid in current list
bIsValid = SetupData.IsValidSerialNumber(sName, sSerialToCheck)
if bIsValid then
-- the serial is valid, break out of the loop
break;
end
end

if bIsValid then
-- The serial number exists in at least one of the lists
Dialog.Message("", "YAY");
else
-- The serial number does not exist in any of the lists
Dialog.Message("", "NAY");
end

Checks if a given serial number is valid in any of the lists in the installer.


SetupData.SetLocalizedString Examples

SetupData.SetLocalizedString

SetupData.SetLocalizedString (

string StringID,

string Text )

Example 1

SetupData.SetLocalizedString("MSG_SUCCESS", "Whatever just happened worked!");

Sets the "Success" string of the current language to "Whatever just happened worked!".


SetupData.SetPackageProperties Examples

SetupData.SetPackageProperties

SetupData.SetPackageProperties (

string PackageName,

table Properties )

Example 1

tProp = SetupData.GetPackageProperties("Default");

Gets the properties of package "Default" and stores them in table "tProp."

Example 2

tProp = SetupData.GetPackageProperties("Default");

tProp.Install = not tProp.Install;

SetupData.SetPackageProperties("Default", tProp);

Gets the properties of package "Default" and stores them in table "tProp." The value of tProp.Install is then toggled (from true to false, or false to true), and the Package properties are set to the new value.

Example 3

sOSName = System.GetOSName();
if sOSName == "Windows XP" then
SetupData.SetPackageProperties("XP_Drivers", {Install=true});
end

Sets the package "XP_Drivers" install flag to true, including this package in the default install, if the current operating system is Windows XP.


SetupData.WriteToLogFile Examples

SetupData.WriteToLogFile

SetupData.WriteToLogFile (

string Text,

boolean AddTimestamp = true )

Example 1

SetupData.WriteToLogFile("ERROR: " .. Application.GetLastError(), true);

Outputs the current application error to the install or uninstall log file.

Example 2

err = Application.GetLastError();

if err ~= 0 then
sMessage = "####################\r\n" .. "ERROR " .. err .. ": " .. _tblErrorMessages[err] .. "\r\n####################\r\n";
SetupData.WriteToLogFile(sMessage, false);
end

If an error occurs, outputs a nicely-formatted string into the install or uninstall log file.


Shell.CreateShortcut Examples

Shell.CreateShortcut

Shell.CreateShortcut (

string Folder,

string Description,

string Target,

string CmdLine = "",

string WorkingFolder = "",

string IconPath = "",

number IconIndex = 0,

number WindowMode = SW_SHOWNORMAL,

table HotKey = nil,

string Comment = "",

number StartPinOption = START_OPTION_DEFAULT )

Example 1

Shell.CreateShortcut(_DesktopFolder, "My Shortcut", "C:\\Program Files\\MyApp\\app.exe", "", "", "C:\\Program Files\\MyApp\\myicon.ico", 0, SW_MAXIMIZE, nil, "This is the comment");

Creates a shortcut on the user's Desktop with the "myicon.ico" file icon and the label "My Shortcut." The shortcut is set to point to the file "app.exe" and will launch it in "maximized" mode.

Note: _DesktopFolder is a built-in variable that contains the path to the user's "Desktop" folder.

Example 2

Shell.CreateShortcut(_DesktopFolder, "My Shortcut", "C:\\Program Files\\MyApp\\app.exe", "", "", "C:\\Program Files\\MyApp\\myicon.ico", 0, SW_MAXIMIZE, {shift=true,ctrl=true,keycode=72});

Creates a shortcut on the user's Desktop with the "myicon.ico" file icon and the label "My Shortcut." The shortcut is set to point to the file "app.exe" and will launch it in "maximized" mode. A hotkey is also assigned to the shortcut so that when you hold down the shift key, the alt key and press the "h" key (Virtual Key Code 72) the application pointed to by the shortcut will be launched.

Note: _DesktopFolder is a built-in variable that contains the path to the user's "Desktop" folder.


Shell.DeleteShortcut Examples

Shell.DeleteShortcut

Shell.DeleteShortcut (

string Folder,

string Description )

Example 1

Shell.DeleteShortcut(_DesktopFolder, "My Shortcut");

Removes the shortcut from the user's Desktop, whose name (description) is "My Shortcut."

Note: _DesktopFolder is a built-in variable that contains the path to the user's "Desktop" folder.


Shell.Execute Examples

Shell.Execute

number Shell.Execute (

string Filename,

string Verb = "open",

string Arguments = "",

string WorkingFolder = "",

number WindowMode = SW_SHOWNORMAL,

boolean WaitForReturn = false )

Example 1

MyDocs = Shell.GetFolder(SHF_MYDOCUMENTS); -- Gets the path to the user's My Documents folder
Shell.Execute(MyDocs .. "\\CompanyInfo.htm", "edit", "", "", SW_SHOWNORMAL);

The first line uses the Shell.GetFolder action to get the path to the user's My Documents folder and stores it in the variable "MyDocs." The file "CompanyInfo.htm" is then opened using the "edit" verb of the Shell.Execute action. This will open the file in the user's associated editor for .htm files.

Example 2

-- Get the session variable and assign it to a regular variable
AppDir = SessionVar.Expand("%AppFolder%");

-- Call a file using the AppDir variable
Shell.Execute(AppDir.."\\Myfile.exe", "open", "", "", SW_SHOWNORMAL);

-- This could also be done as such
Shell.Execute(SessionVar.Expand("%AppFolder%").."\\Myfile.exe", "open", "", "", SW_SHOWNORMAL);

This example shows two ways of using a Shell.Execute action with a session variable.


Shell.GetFolder Examples

Shell.GetFolder

string Shell.GetFolder (

number Type )

Example 1

Desktop_Folder = Shell.GetFolder(SHF_DESKTOP_COMMON);

Gets the path to the user's Desktop folder and stores the string in the variable "Desktop_Folder."

Example 2

My_Docs = Shell.GetFolder(SHF_MYDOCUMENTS);

Gets the path to the user's "My Documents" folder and stores the string in the variable "My_Docs."

Example 3

My_Docs = Shell.GetFolder(5);

Gets the path to the user's "My Documents" folder and stores the string in the variable "My_Docs." Example 2 used the SHF_MYDOCUMENTS constant, however this example shows that you can also use it's numeric value.

Example 4

-- Get the path to the user's My Documents folder.
myDocs = Shell.GetFolder(SHF_MYDOCUMENTS);

-- Open the user's My Documents folder in an explore window.
File.ExploreFolder(myDocs, SW_SHOWNORMAL);

Gets the path to the user's "My Documents" folder and stores the string in the variable "myDocs." The folder is then opened in a explore window using the File.ExploreFolder action.


Status Dialog

Overview

The Status Dialog in Setup Factory is a Windows dialog containing a progress meter and some optional elements such as a cancel button, icon, title bar text and status text. It was designed to allow you to optionally display a graphical representation of the progress made in a Setup Factory action or any other element of your project. An example of the dialog can be seen below:

There are several actions in Setup Factory that automatically use this dialog to show their progress (if you wish to show it):

  • File.Copy

  • File.Delete

  • File.Find

  • File.Install

  • File.Move

  • Folder.DeleteTree

  • Folder.Find

  • HTTP.Download

  • HTTP.DownloadSecure

  • HTTP.GetFileSize

  • HTTP.GetFileSizeSecure

Each action above automatically sends progress information to the status dialog in order to display its meter progress. By default, the Status Dialog is hidden, but you can show it by preceding the action with a StatusDlg.Show action and following it with a StatusDlg.Hide action. The StatusDlg.Show action is used to show the Status Dialog and the StatusDlg.Hide action is used to hide it, usually after the action has completed. You can find other available actions in the StatusDlg action category.

For this group of actions, this functionality is handled automatically, however you also have the ability to override it. Each action contains a parameter called CallbackFunction. By default the CallbackFunction parameter is set to nil. This means it will automatically pass progress information to the Status Dialog. However in some cases you may need further control over what, and how it is displayed. In this situation you can pass a function as the CallbackFunction parameter (you will need to consult the action being used for the required parameters of the function). You can find an example illustrating this method in the article, Create a custom callback function.

Until this point, the status dialog has been described in relation to specific actions in Setup Factory. However due to its flexibility and power, it can be used in many other ways. The Status Dialog contains it's own category of actions called StatusDlg and can be used to provide a representation for any type of progress you need.


StatusDlg.GetAutoSize Examples

StatusDlg.GetAutoSize

boolean StatusDlg.GetAutoSize (

)

Example 1

bAutoSize = StatusDlg.GetAutoSize();

Stores the built-in status dialog's auto-size settings in the variable "bAutoSize."


StatusDlg.GetMeterPos Examples

StatusDlg.GetMeterPos

number StatusDlg.GetMeterPos (

)

Example 1

meter_position = StatusDlg.GetMeterPos();

Gets the current status meter position on the status dialog and stores it in a variable called "meter_position."


StatusDlg.Hide Examples

StatusDlg.Hide

StatusDlg.Hide (

)

Example 1

StatusDlg.Hide();

Hides the built-in status dialog that is currently displayed.

Example 2

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Set statusdlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);
end

-- Show the StatusDlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the Status Dialog.


StatusDlg.IsCancelled Examples

StatusDlg.IsCancelled

boolean StatusDlg.IsCancelled (

)

Example 1

clicked = StatusDlg.IsCancelled();

Determines whether or not the cancel button on the built-in status dialog has been clicked and stores either true or false in the variable "clicked."


StatusDlg.SetAutoSize Examples

StatusDlg.SetAutoSize

StatusDlg.SetAutoSize (

boolean AutoSize )

Example 1

StatusDlg.SetAutoSize(true);

Allows the built-in status dialog to automatically resize if needed.

Example 2

StatusDlg.SetAutoSize(false);

Prevents the built-in status dialog from automatically resizing.


StatusDlg.SetCancelled Examples

StatusDlg.SetCancelled

StatusDlg.SetCancelled (

boolean Cancelled )

Example 1

StatusDlg.SetCancelled(true);

Sets the status dialog's cancel button state to clicked.


StatusDlg.SetMessage Examples

StatusDlg.SetMessage

StatusDlg.SetMessage (

string Text )

Example 1

StatusDlg.SetMessage("Please wait while we process your request.");

Sets the built-in status dialog's main description to the string, "Please wait while we process your request."


StatusDlg.SetMeterPos Examples

StatusDlg.SetMeterPos

StatusDlg.SetMeterPos (

number Position )

Example 1

StatusDlg.SetMeterPos(25);

Sets the status dialog's status meter to a position of 25.

Example 2

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Set statusdlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);
end

-- Show the StatusDlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the Status Dialog.


StatusDlg.SetMeterRange Examples

StatusDlg.SetMeterRange

StatusDlg.SetMeterRange (

number Begin,

number End )

Example 1

StatusDlg.SetMeterRange(0, 100);

Sets the meter range of the built-in status dialog to a beginning value of 0 and an end value of 100.

Example 1

StatusDlg.SetMeterRange(0, 5000);

Sets the meter range of the built-in status dialog to a beginning value of 0 and an end value of 5000.


StatusDlg.SetStatusText Examples

StatusDlg.SetStatusText

StatusDlg.SetStatusText (

string Text )

Example 1

StatusDlg.SetStatusText("Copying files...");

Sets the built-in status dialog's status text to the string, "Copying files..."


StatusDlg.SetTitle Examples

StatusDlg.SetTitle

StatusDlg.SetTitle (

string Text )

Example 1

StatusDlg.SetTitle("Verifying information...");

Sets the built-in status dialog's title bar text to the string "Verifying information..."


StatusDlg.Show Examples

StatusDlg.Show

StatusDlg.Show (

number Icon = 0,

boolean Cancelled = false )

Example 1

StatusDlg.Show(MB_ICONINFORMATION, false);

Displays the built-in status dialog with the information icon. The "false" parameter indicates that the cancel button hasn't been pressed.

Example 2

StatusDlg.Show(MB_ICONNONE, true);

Displays the built-in status dialog with no icon. The "true" parameter indicates that the cancel button has been pressed.

Example 3

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Set statusdlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);
end

-- Show the StatusDlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the Status Dialog.


StatusDlg.ShowCancelButton Examples

StatusDlg.ShowCancelButton

StatusDlg.ShowCancelButton (

boolean ShowCancel = true,

string ButtonText = "Cancel" )

Example 1

StatusDlg.ShowCancelButton(true, "Abort");

Shows the cancel button on the built-in status dialog and sets it's text to "Abort."

Example 2

StatusDlg.ShowCancelButton(false);

Hides the cancel button on the built-in status dialog.


StatusDlg.ShowProgressMeter Examples

StatusDlg.ShowProgressMeter

StatusDlg.ShowProgressMeter (

boolean Show = true )

Example 1

StatusDlg.ShowProgressMeter(true);

Shows the progress meter on the status dialog.

Example 2

StatusDlg.ShowProgressMeter(false);

Hides the progress meter on the status dialog.


String.AbbreviateFilePath Examples

String.AbbreviateFilePath

string String.AbbreviateFilePath (

string FilePath,

number Characters )

Example 1

internal_path = "c:\\windows\\system32\\drivers\\ta_da\\foldername\\driver.vxd";
display_path = String.AbbreviateFilePath(internal_path, 30);

Converts the lengthy internally used path into a more managable size to display to the user (c:\windows\...\driver.vxd)

Example 2

-- callback function for File.Delete action
function DeleteCallBack(source, deleted, total)
-- set the message and status text
StatusDlg.SetMessage("Delete: " .. String.AbbreviateFilePath(source, 10));
StatusDlg.SetStatusText("File " .. deleted .. " of " .. total .. ".");

-- show the cancel button
StatusDlg.ShowCancelButton(true, "Cancel");

-- check if the cancel button was pressed
bCancel = StatusDlg.IsCancelled();

-- if the cancel button was pressed, return false, else return true.
if bCancel then
return false;
else
return true;
end
end

-- show the status dialog
StatusDlg.Show();

-- delete all files in folder c:\temp, using the DeleteCallBack function
File.Delete("c:\\temp\\*.*", true, true, true, DeleteCallBack);

-- Hide the status dialog
StatusDlg.Hide();

Deletes all files and folders from c:\temp, and uses a callback function to display status to the user.


String.Asc Examples

String.Asc

number String.Asc (

string Char )

Example 1

code = String.Asc("h");

Gets the ASCII code of the character "h" and stores it in the variable "code." The number 104 will be stored as a result.


String.Char Examples

String.Char

string String.Char (

number ASCII )

Example 1

character = String.Char(104);

Gets the character value of the ASCII code 104 and stores the result in the variable "character." The character "h" will be stored as a result.


String.Compare Examples

String.Compare

number String.Compare (

string Text,

string CompareTo )

Example 1

compare_result = String.Compare("John", "Mary");

Compares the string "John" to the string "Mary" and stores the result in the variable "compare_result." Since "John" is less than "Mary", the number -1 would be returned.

Example 2

IsBigger = String.Compare("Bob", "Bob");

Compares the string "Bob" to the second string "Bob" and stores the result in the variable "IsBigger." Since both strings are the same, the number 0 would be returned.

Example 3

IsBigger = String.Compare("Bob", "bob");

Compares the string "Bob" to the second string "bob" and stores the result in the variable "IsBigger." Since the comparison is case-sensitive, the strings are not the same. The string "Bob" is less than the string "bob", therefore the number -1 would be returned.


String.CompareFileVersions Examples

String.CompareFileVersions

number String.CompareFileVersions (

string Version,

string CompareTo )

Example 1

compare_version = String.CompareFileVersions("1.0.20.3", "1.0.2.3");

Compares the file version string "1.0.20.3" to version "1.0.2.3" and stores the result in the variable "compare_version." Since "1.0.20.3" is greater than "1.0.2.3", the number 1 would be returned.

Example 2

IsBigger = String.CompareFileVersions("1.0.0.1", "1.0.0.1");

Compares the file version "1.0.0.1" to "1.0.0.1" and stores the result in the variable "IsBigger." Since the version strings are identical, the number 0 would be returned.

Example 3

-- Get the current OS Version information
tVersionInfo = System.GetOSVersionInfo();

-- Combine Version information into a file-version string
sCurrentWindowsVersion = tVersionInfo.MajorVersion .. "." .. tVersionInfo.MinorVersion.. "." .. tVersionInfo.BuildNumber;

-- Specify the minimum required file version
sRequiredWindowsVersion = "5.1.2600";

-- Compare the current file version to the minimum requirement
nCompareResult = String.CompareFileVersions (sRequiredWindowsVersion, sCurrentWindowsVersion);

-- If the minimum requirement is greater than the current version, display an error and exit.
if (nCompareResult == 1) then
Dialog.Message("Error", "Windows XP or later is required to use this software.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
Application.Exit();
end

Gets the Operating System's version information, and compares it to a minimum value. If the installed operating system is not Windows XP or later (version 5.1.2600 or newer), an error message is displayed.


String.CompareNoCase Examples

String.CompareNoCase

number String.CompareNoCase (

string Text,

string CompareTo )

Example 1

compare_result = String.CompareNoCase("John", "Mary");

Compares the string "John" to the string "Mary" and stores the result in the variable "compare_result." Since "John" is less than "Mary", the number -1 would be returned.

Example 2

IsBigger = String.CompareNoCase("Bob", "Bob");

Compares the string "Bob" to the second string "Bob" and stores the result in the variable "IsBigger." Since both strings are the same, the number 0 would be returned.

Example 3

IsSame = String.CompareNoCase("BOB", "bob");

Compares the string "BOB" to the second string "bob" and stores the result in the variable "IsSame." Since the comparison is case-insensitive, the strings are the same, therefore the number 0 would be returned.


String.Concat Examples

String.Concat

string String.Concat (

string StartString,

string EndString )

Example 1

result_string = String.Concat("One", "Two");

Creates the new string "OneTwo" by appending the string "Two" to the string "One." The new string is returned in the variable "result_string."


String.Find Examples

String.Find

number String.Find (

string SearchString,

string Pattern,

number StartAt = 1,

boolean CaseSensitive = false )

Example 1

target_index = String.Find("Indigo Rose, the company who cares.", "company", 1, false);

Searches the string "Indigo Rose, the company who cares." for the sub-string "company" and returns the first position it was found. In this example, the variable "target_index" would contain the number 18.

Example 2

target_index = String.Find("The mean Boy popped my balloon. I think that Boy needs therapy.", "Boy", 13, true);

Performs a case-sensitive search on the string "That mean boy popped my balloon. I think that boy needs therapy." for the sub-string "Boy" starting at position 13 in the string. In this example, the variable "target_index" would contain the number 46 since it is the first occurrence of "Boy" after position 13 in the string.


String.GetFormattedSize Examples

String.GetFormattedSize

string String.GetFormattedSize (

number SizeInBytes,

number Format = FMTSIZE_AUTOMATIC,

boolean ShowCommas = true )

Example 1

sFormatted = String.GetFormattedSize(nBytes, FMTSIZE_AUTOMATIC, true);

Converts the value in nBytes from number of bytes to a formatted string. The best format based on the size is automatically chosen, and is stored in sFormatted.

Example 2

-- Callback function for HTTP.Download
function DownloadCallback (nDownloaded, nTotal, TransferRate, SecondLeft, SecondsLeftFormat, Message)
-- Convert total and downloaded bytes into formatted strings
sDownloaded = String.GetFormattedSize(nDownloaded, FMTSIZE_AUTOMATIC, true);
sTotal = String.GetFormattedSize(nTotal, FMTSIZE_AUTOMATIC, true);

-- Set statusdlg title and message
StatusDlg.SetTitle("Downloading . . . ");

-- Output time left, formatted.
StatusDlg.SetMessage("Currently downloading file . . . Time Left: " .. SecondsLeftFormat);

-- Output formatted sizes to user through statusdlg status text
StatusDlg.SetStatusText("Downloaded: " .. sDownloaded .. " / " .. sTotal);

-- Set meter range (max range = 65534)
StatusDlg.SetMeterRange(0, 65534);

-- Set meter position (fraction downloaded * max meter range)
StatusDlg.SetMeterPos((nDownloaded / nTotal) * 65534);
end

-- Show the StatusDlg
StatusDlg.Show(0, false);

-- Download a file from the internet to the user's computer
-- Uses DownloadCallback() as the callback function
HTTP.Download("http://www.yourdomain.com/downloads/update.exe", _TempFolder .. "\\update.exe", MODE_BINARY, 20, 80, nil, nil, DownloadCallback);

-- Hide the StatusDlg
StatusDlg.Hide();

Downloads a file from the internet onto the user's computer. The callback function "DownloadCallback" controls the Status Dialog.


String.Left Examples

String.Left

string String.Left (

string LeftString,

number NumChar )

Example 1

left_string = String.Left("Hey There", 3);

Returns a string containing the first three characters of "Hey There." Therefore the string "Hey" will be stored in the variable "left_string."


String.Length Examples

String.Length

number String.Length (

string LengthString )

Example 1

size = String.Length("Hey There");

Gets the length of the string "Hey There" and stores it in the variable "size." In this example, the number 9 would be returned.


String.Lower Examples

String.Lower

string String.Lower (

string ToLower )

Example 1

string_small = String.Lower("Indigo Rose");

Takes the string "Indigo Rose" and returns an all lowercase version of the string in the variable "string_small." The variable "string_small" would contain the new string "indigo rose."


String.MakePath Examples

String.MakePath

string String.MakePath (

table PathParts )

Example 1

Debug.ShowWindow(true); --Shows the debug window.
path_parts = {Drive="C:",Folder="\\MyFolder1\\MyFolder2\\",Filename="myfile",Extension=".exe"};
result_path = String.MakePath(path_parts);
Debug.Print(result_path);

In this example, a table called "path_parts" is first created containing each part of a path. The String.MakePath action is then used to create a path string based upon the elements of the table and then printed to the debug window. The created string would look like this:

C:\MyFolder1\MyFolder2\myfile.exe

Example 2

Debug.ShowWindow(true); --Shows the debug window.
path_parts = {Drive="C:",Folder="\\",Filename="myfile",Extension=".exe"};
result_path = String.MakePath(path_parts);
Debug.Print(result_path);

This example is the same as example 1, however the Folder element only contains the required backslash. The debug window output would look like this:

C:\myfile.exe

Note: A backslash must be added to the Folder value, even if no folders are present in the path.


String.Mid Examples

String.Mid

string String.Mid (

string MidString,

number CharStart,

number NumChar )

Example 1

color_string = String.Mid("The red balloon", 5, 3);

Copies 3 characters from the string "The red balloon" starting at position 5. This will store "red" in the variable named color_string.

Example 2

strEnd = String.Mid("The red balloon", 12, -1);

Copies everything from the 12th character in "The red balloon" to the end of the string. This will store "loon" in a variable named strEnd.

Example 3

filename = String.Mid(filepath, String.ReverseFind(filepath, "\\") + 1, -1);

Copies the filename from the path stored in the variable "filepath" and stores it in a variable named "filename."


String.Repeat Examples

String.Repeat

string String.Repeat (

string RepeatString,

number NumRepeat )

Example 1

multi_string = String.Repeat("One", 4);

Repeats the string "One" four times to create the new string "OneOneOneOne", and stores it in the variable "multi_string."


String.Replace Examples

String.Replace

string String.Replace (

string SearchString,

string Pattern,

string ReplaceString,

boolean CaseSensitive = false )

Example 1

replaced_string = String.Replace("My red balloon matches my red hat.", "red", "blue", false);

Searches the source string "My red balloon matches my red hat." for the sub-string "red" and replaces it with the new sub-string "blue". The new string "My blue balloon matches my blue hat." will be returned in the variable "replaced_string."

Example 2

replaced_string = String.Replace("My Red balloon matches my red hat.", "Red", "blue", true);

Performs a case-sensitive search on the source string "My red balloon matches my red hat." for the sub-string "Red" and replaces it with the new sub-string "blue". The new string "My blue balloon matches my red hat." will be returned in the variable "replaced_string." You will notice that the second occurrence of the string "red" was not replaced due to the difference in character case.

Example 3

-- Read the contents of a text file into a string.
contents = TextFile.ReadToString("C:\\MyFile.txt");

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Replace every occurrence of the string "Robert" with the string "Adam".
new_contents = String.Replace(contents, "Robert", "Adam", true);

-- Write out the modified contents of the text file.
TextFile.WriteFromString("C:\\MyFile.txt", new_contents, false);

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of the file "MyFile.txt" and stores the string in the variable "contents." Every occurrence of the string "Robert" in "contents" is replaced with the string "Adam" and then written back to the text file "MyFile.txt".


String.ReverseFind Examples

String.ReverseFind

number String.ReverseFind (

string SearchString,

string Pattern,

boolean CaseSensitive = false )

Example 1

target_index = String.ReverseFind("The mean Boy popped my balloon. I think that Boy needs therapy.", "Boy", true);

Performs a case-sensitive search on the string "That mean boy popped my balloon. I think that boy needs therapy." for the sub-string "Boy" starting from the end of the string. In this example, the variable "target_index" would contain the number 46 since it is the first occurrence of "Boy" when searched from right to left.


String.Right Examples

String.Right

string String.Right (

string RightString,

number NumChar )

Example 1

right_string = String.Right("Hey There", 5);

Returns a string containing the last five characters of "Hey There." Therefore the string "There" will be stored in the variable "right_string."


String.SplitPath Examples

String.SplitPath

table String.SplitPath (

string Path )

Example 1

Debug.ShowWindow(true); --Shows the debug window.
path_parts = String.SplitPath("C:\\MyFolder1\\MyFolder2\\myfile.exe");
Debug.Print(path_parts.Drive.."\r\n");
Debug.Print(path_parts.Folder.."\r\n");
Debug.Print(path_parts.Filename.."\r\n");
Debug.Print(path_parts.Extension.."\r\n");

Takes a file path and splits it up into it's drive, folders, filename and file extension components using the String.SplitPath action. Each part of the path is stored in the table named "path_parts." In this example, each table value is printed to the debug window and would look like this:

C:
\MyFolder1\MyFolder2\
myfile
.exe

Example 2

Debug.ShowWindow(true); --Shows the debug window.
path_parts = String.SplitPath("C:\\myfile.exe");
Debug.Print(path_parts.Drive.."\r\n");
Debug.Print(path_parts.Folder.."\r\n");
Debug.Print(path_parts.Filename.."\r\n");
Debug.Print(path_parts.Extension.."\r\n");

This example is the same as example 1, however this path does not contain any folders. The debug window output would look like this:

C:
\
myfile
.exe

Example 3

Debug.ShowWindow(true); --Shows the debug window.
path_parts = String.SplitPath("C:\\MyFolder1\\MyFolder2\\");
Debug.Print(path_parts.Drive.."\r\n");
Debug.Print(path_parts.Folder.."\r\n");
Debug.Print(path_parts.Filename.."\r\n");
Debug.Print(path_parts.Extension.."\r\n");

Again, this example is the same as above, however this path does not contain a filename. The debug window output would look like this:

C:
\MyFolder1\MyFolder2\

Note: The Filename and Extension values will return blank. In order for this action to work on partial paths, there must be a trailing backslash in the source path to indicate it is a folder and not a filename.


String.ToNumber Examples

String.ToNumber

number String.ToNumber (

string NumericString )

Example 1

number_format = String.ToNumber("84");
if number_format < 100 then
Dialog.Message("Successful", "Yes, the number "..number_format.." is less than 100.");
end

Converts the string "84" to the number 84 so it can be used in a numeric comparison that will display a message to the user.


String.TrimLeft Examples

String.TrimLeft

string String.TrimLeft (

string SourceString,

string CharactersToTrim = nil )

Example 1

trimmed = String.TrimLeft("12324", "21");

Removes the characters in the string "21" from the source string "12324" and stores the resulting string "324" in the variable "trimmed."

Example 2

trimmed_space = String.TrimLeft(" Bob", nil);

Removes the beginning spaces from the source string and returns the string "Bob" in the variable "trimmed_space."


String.TrimRight Examples

String.TrimRight

string String.TrimRight (

string SourceString,

string CharactersToTrim = nil )

Example 1

trimmed = String.TrimRight("14345", "54");

Removes the characters in the string "54" from the source string "14345" and stores the resulting string "143" in the variable "trimmed."

Example 2

trimmed_space = String.TrimRight("Bob ", nil);

Removes the trailing spaces from the source string and returns the string "Bob" in the variable "trimmed_space."


String.Upper Examples

String.Upper

string String.Upper (

string ToUpper )

Example 1

string_large = String.Upper("Indigo Rose");

Takes the string "Indigo Rose" and returns an all uppercase version of the string in the variable "string_large." The variable "string_large" would contain the new string "INDIGO ROSE."


System.EnumerateProcesses Examples

System.EnumerateProcesses

table System.EnumerateProcesses (

)

Example 1

open_processes = System.EnumerateProcesses();

Gets the process IDs and executable file paths for every process that is currently running and stores them in a table named open_processes.

Example 2

instances_of_file = 0;
file_to_check_for = "dummy.exe"; --have all lowercase
processes = System.EnumerateProcesses();

for j, file_path in pairs(processes) do
file = String.SplitPath(file_path);
if (String.Lower(file.Filename..file.Extension)) == file_to_check_for then
System.TerminateProcess(j);
end
end

Terminates all processes that were spawned by the executable "dummy.exe."


System.GetDate Examples

System.GetDate

string System.GetDate (

number DateType )

Example 1

current_date_sortable = System.GetDate(2); -- ISO date format sorts nicely

Get's the current date in ISO format (YYYY-MM-DD) and stores it in the variable "current_date_sortable."

Example 2

days_since_Jan_15_2003 = System.GetDate(3)-2452655; -- 2452655 is the Julian date for Jan 15, 2003

Subtracts the Julian date for Jan 15, 2003 from the current Julian date and stores the result in the variable "days_since_Jan_15_2003". The Julian date format is perfect for date comparisons.

Example 3

nWeekday = System.GetDate(7);

Returns the current day of the week (1-7) in the variable "nWeekday."

Example 4

-- Specify the length of the trial period, in days
time_limit = 30;

-- Initialize days_left
days_left = 0;

-- Retrieve previous value stored
date_installed = Application.LoadValue("My Application", "Date Installed");-- Convert loaded value into a number
date_installed = String.ToNumber(date_installed);

-- If there is no previous value (date_installed == 0), create a value
if date_installed == 0 then
Application.SaveValue("My Application", "Date Installed", System.GetDate(DATE_FMT_JULIAN));
days_left = time_limit;
else
days_left = (date_installed + time_limit) - System.GetDate(DATE_FMT_JULIAN);
end

-- Check if there is time left
if String.ToNumber(days_left) < 1 then
Dialog.Message("Trial Period Over", "This software has expired");
Application.Exit();
else
Dialog.Message("Trial Period", "You have "..days_left.." days left in your trial period.");
end

Notifies the user after thirty days that the installation has expired and exits.


System.GetDefaultLangID Examples

System.GetDefaultLangID

table System.GetDefaultLangID (

)

Example 1

language_info = System.GetDefaultLangID();

Gets the primary and secondary language ID code and stores them in the table called "language_info." These values could be accessed by referencing language_info.Primary and language_info.Secondary.

Example 2

-- Retrieve the system's default language ID's
tLangID = System.GetDefaultLangID();

-- Check if default primary language is english (English = 9)
if tLangID.Primary == 9 then
-- Default primary language is english
Dialog.Message("Default Language", "Your default language is English!");
else
-- Default primary language is not english
Dialog.Message("Default Language", "Your default language is not English!");
end

Retrieves the system's default language ID's, compares the primary ID to the value representing English (9), and displays an appropriate message.


System.GetDisplayInfo Examples

System.GetDisplayInfo

table System.GetDisplayInfo (

)

Example 1

screen_info = System.GetDisplayInfo();

Gets the screen width, height and color depth of the user's system and stores the information in a table called "screen_info." This information can be accessed by referencing screen_info.Width, screen_info.Height and screen_info.ColorDepth. If the user's resolution was set to 800 x 600, screen_info.Width would contain the value 800 and screen_info.Height would contain 600. It's color depth may be a value such as 32.

Example 2

-- Get the user's display information.
display = System.GetDisplayInfo();

if (display ~= nil) then
-- If the user's running less than 800 x 600, display a dialog.
if (display.Height < 600) then
Dialog.Message("Notice", "Your resolution is currently set to "..display.Width.." x "..display.Height..".\r\n"..
"You must have at least 800 x 600 to view this application properly.", MB_OK, MB_ICONINFORMATION);
end
end

Gets the user's screen resolution and stores it in a table called "display." If the user has a resolution that is less than 800 x 600, a dialog is displayed notifying them of the application requirement.


System.GetLANInfo Examples

System.GetLANInfo

table System.GetLANInfo (

)

Example 1

LAN_info = System.GetLANInfo();

Gets the system's LAN information and stores it in a table called "LAN_info." If you wanted the network domain the user was logged into, you could access it by referencing LAN_info.Domain.

Example 2

lan = System.GetLANInfo();
lan_exist = true;
for j in pairs(lan) do
if lan[j] == "Unknown" then
lan_exist = false;
end
end

if lan_exist then
Dialog.Message("", "You are connected to a LAN");
else
Dialog.Message("", "You are not connected to a LAN");
end

Determines whether or not the user is connected to a LAN and displays the result in a dialog message.


System.GetMemoryInfo Examples

System.GetMemoryInfo

table System.GetMemoryInfo (

)

Example 1

-- Get the memory information from the user's system.
tbMemory = System.GetMemoryInfo();

-- Display an error message if their RAM is less than 500 MB.
if (tbMemory.TotalRAM < 500) then
Dialog.Message("Warning", "This application requires at least 512 MB of RAM.\r\nYou currently only have "..tbMemory.TotalRAM.." MB RAM.");
end

Gets the amount of RAM on the user's system and warns them if their RAM is less than 500 MB.


System.GetOSName Examples

System.GetOSName

string System.GetOSName (

)

Example 1

OS_Name = System.GetOSName();

Get's the name of the OS the user is running and stores the string in the variable "OS_Name."

Example 2

-- Get the name of the OS.
os_name = System.GetOSName();

-- Display the name of the OS in a dialog.
Dialog.Message("Information", "Your operating system is "..os_name..".", MB_OK, MB_ICONINFORMATION);

Get's the name of the OS the user is running and displays it in a dialog message.


System.GetOSProductInfo Examples

System.GetOSProductInfo

number System.GetOSProductInfo (

)

Example 1

nInfo = System.GetOSProductInfo();

if (nInfo == PRODUCT_HOME_BASIC) then
Dialog.Message("Product Info", "The operating system is Home Basic.");
end

Determines whether the operating system is Home Basic and shows a dialog message.


System.GetOSVersionInfo Examples

System.GetOSVersionInfo

table System.GetOSVersionInfo (

)

Example 1

OS_info = System.GetOSVersionInfo();

Get's the version information of the OS the user is running and stores it's results in a table called "OS_info." If you wanted the major version number, you could access it by referencing OS_info.MajorVersion.

Example 2

-- Get the current OS Version information
tVersionInfo = System.GetOSVersionInfo();

-- Combine Version information into a file-version string
sCurrentWindowsVersion = tVersionInfo.MajorVersion .. "." .. tVersionInfo.MinorVersion.. "." .. tVersionInfo.BuildNumber;

-- Specify the minimum required file version
sRequiredWindowsVersion = "5.1.2600";

-- Compare the current file version to the minimum requirement
nCompareResult = String.CompareFileVersions (sRequiredWindowsVersion, sCurrentWindowsVersion);

-- If the minimum requirement is greater than the current version, display an error and exit.
if (nCompareResult == 1) then
Dialog.Message("Error", "Windows XP or later is required to use this software.", MB_OK, MB_ICONSTOP, MB_DEFBUTTON1);
Application.Exit();
end

Gets the Operating System's version information, and compares it to a minimum value. If the installed operating system is not Windows XP or later (version 5.1.2600 or newer), an error message is displayed.


System.GetTime Examples

System.GetTime

string System.GetTime (

number TimeType )

Example 1

current_time = System.GetTime(0);

Stores the current military time (HH:MM:SS) in the variable "current_time."

Example 2

mmhh = System.GetTime(3) ..":".. System.GetTime(4);

Stores the current minute, followed by a colon and the current hour in the variable "mmhh."

Note: The concatenation operator (..) is used to add the current minute followed by the ":" character and the current hour.

Example 3

wordytime = System.GetTime(4) .." hours, ".. System.GetTime(3) .." minutes and ".. System.GetTime(2) .." seconds";

Stores a string containing the current hour, minute, and second in the variable "wordytime." The result may look something like, "6 hours 42 minutes and 30 seconds."


System.GetUserInfo Examples

System.GetUserInfo

table System.GetUserInfo (

)

Example 1

user_info = System.GetUserInfo();

Gets the current user's information and stores it in the "user_info" table.

Example 2

user_info = System.GetUserInfo();
if (not user_info.IsAdmin) then
Dialog.Message("Warning", "You are not logged in with the appropriate permissions.");
end

Checks to see if the current user is logged in with administrator permissions and if they are not, displays a dialog box informing them.

In this example, the registered user and organization could be accessed by referencing user_info.RegOwner and user_info.RegOrganization.

Example 3

user_info = System.GetUserInfo();
if (user_info.IsAdmin or user_info.IsVistaAdminLimitedToken) then
Shell.Execute(_TempFolder.."\\MyProg.exe", "open", "", "", SW_SHOWNORMAL);
else
Dialog.Message("Warning", "You are not logged in with the appropriate permissions.");
end

Checks to see if the current user is a member of the Administrators group who is either running with full privileges, or can be elevated to these privileges on Vista or later in order to run "MyProg.exe." If they are not, a dialog box is shown informing them.


System.GetUserSID Examples

System.GetUserSID

string System.GetUserSID (

string UserName )

Example 1

strUserName = "test_user1";
strUserSID = System.GetUserSID(strUserName);
if (strUserSID == "") then
strMessage = "ERROR: Unable to get SID for \""..strUserName.."\" code: "..System.UserSIDError.. "\r\n";
SetupData.WriteToLogFile(strMessage, false);
end

Gets the SID value for the user name "test_user1" and if it fails, writes the system error code to the setup log file.


System.Is64BitOS Examples

System.Is64BitOS

boolean System.Is64BitOS (

)

Example 1

if (System.Is64BitOS()) then
-- The user's system is running a 64 bit operating system.
end

Checks if the user's OS is 64 bit.

Example 2

-- Check if the OS is 64 bit
b64Bit = System.Is64BitOS();

if b64Bit then
-- The OS is 64 bit
else
-- The OS is not 64 bit.
end

Performs specific tasks based on whether or not the user's system is running a 64 bit OS.


System.IsSystemRestoreAvailable Examples

System.IsSystemRestoreAvailable

boolean System.IsSystemRestoreAvailable (

)

Example 1

bRestore = System.IsSystemRestoreAvailable();

Stores true in the variable "bRestore" if the system restore service is available, or false if not.

Example 2

-- Check to see if the system has system restore capability
bSysRestoreAvailable = System.IsSystemRestoreAvailable();

if bSysRestoreAvailable then
-- Restore is available, mark start point
nSequenceNum = System.SetRestorePoint(SYSTEM_CHANGE_BEGIN, SYS_RESTORE_APP_INSTALL, 0, "Installed Sample Product v. 3.7")
else
-- Restore is unavailable, confirm with the user to continue
nChoice = Dialog.Message("Restore Unavailable", "Your system does not support System Restore. Do you want to continue with the setup?", MB_YESNO, MB_ICONSTOP);

if nChoice == 7 then
-- The user chose not to continue, exit the script
Application.ExitScript();
end
end

-- DO UPDATE TASKS HERE

if bSysRestoreAvailable then
-- Restore is available, mark end point
nSequenceNum = System.SetRestorePoint(SYSTEM_CHANGE_END, SYS_RESTORE_APP_INSTALL, nSequenceNumber, "Installed Sample Product v. 3.7")

-- Write sequence number to the registry for later use
Registry.SetValue(HKEY_LOCAL_MACHINE, SessionVar.Expand("Software\\%CompanyName%\\%ProductName%\\RestorePointInfo"), "SequenceNumber", nSequenceNum, REG_SZ)
end

Checks if the user's system supports system restore. If it does not, the user is asked if the setup should continue. If the system supports system restore, or the user chooses to continue, a restore point is set and the setup tasks are completed.


System.Reboot Examples

System.Reboot

System.Reboot (

)

Example 1

System.Reboot();

Reboots the user's system.


System.RegisterActiveX Examples

System.RegisterActiveX

System.RegisterActiveX (

string Filename )

Example 1

System.RegisterActiveX(_SystemFolder .. "\\mycontrol.ocx");

Registers the ActiveX control named "mycontrol.ocx" located in the user's system folder.

Note: _SystemFolder is a built-in variable that contains the path to the user's "System" folder.


System.RegisterFont Examples

System.RegisterFont

System.RegisterFont (

string Filename,

string Fontname,

boolean Permanent = true )

Example 1

fonts_dir = Shell.GetFolder(SHF_FONTS); -- Gets the path to the user's Font directory.
System.RegisterFont(fonts_dir .. "\\myfont.ttf", "Crazy Font", true);

The first line uses the Shell.GetFolder action to get the path to the user's Font directory and stores it's path in the variable "fonts_dir." The second action permanently registers the font file named "myfont.ttf" on the user's local system with the name "Crazy Font."


System.RegisterTypeLib Examples

System.RegisterTypeLib

System.RegisterTypeLib (

string Filename )

Example 1

System.RegisterTypeLib(_SystemFolder .. "\\myfile.tlb");

Registers the type library file named "myfile.tlb" located in the user's system folder.

Note: _SystemFolder is a built-in variable that contains the path to the user's "System" folder.


System.RemoveRestorePoint Examples

System.RemoveRestorePoint

System.RemoveRestorePoint (

number SequenceNum )

Example 1

System.RemoveRestorePoint(107);

Removes the system restore point whose sequence number is 107.

Example 2

-- Get the sequence number of the restore point to remove
nSequenceNum = Registry.GetValue(HKEYHKEY_LOCAL_MACHINE, SessionVar.Expand("Software\\%CompanyName%\\%ProductName%\\RestorePointInfo"), "SequenceNumber", false)

-- Remove the restore point
System.RemoveRestorePoint(nSequenceNum);

Gets a sequence number from the registry, and removes the corresponding restore point.


System.SetRestorePoint Examples

System.SetRestorePoint

number System.SetRestorePoint (

number EventType,

number RestorePointType,

number SequenceNum,

string Description )

Example 1

nSeqNum = System.SetRestorePoint(SYSTEM_CHANGE_BEGIN, SYS_RESTORE_APP_INSTALL, 0, "My Program Install");

Begins a system restore point of an application install and returns the sequence number in the variable "nSeqNum."

Example 2

-- Check to see if the system has system restore capability
bSysRestoreAvailable = System.IsSystemRestoreAvailable();

if bSysRestoreAvailable then
-- Restore is available, mark start point
nSequenceNum = System.SetRestorePoint(SYSTEM_CHANGE_BEGIN, SYS_RESTORE_APP_INSTALL, 0, "Installed Sample Product v. 3.7")
else
-- Restore is unavailable, confirm with the user to continue
nChoice = Dialog.Message("Restore Unavailable", "Your system does not support System Restore. Do you want to continue with the setup?", MB_YESNO, MB_ICONSTOP);

if nChoice == 7 then
-- The user chose not to continue, exit the script
Application.ExitScript();
end
end

-- DO UPDATE TASKS HERE

if bSysRestoreAvailable then
-- Restore is available, mark end point
nSequenceNum = System.SetRestorePoint(SYSTEM_CHANGE_END, SYS_RESTORE_APP_INSTALL, nSequenceNumber, "Installed Sample Product v. 3.7")

-- Write sequence number to the registry for later use
Registry.SetValue(HKEY_LOCAL_MACHINE, SessionVar.Expand("Software\\%CompanyName%\\%ProductName%\\RestorePointInfo"), "SequenceNumber", nSequenceNum, REG_SZ)
end

Checks if the user's system supports system restore. If it does not, the user is asked if the setup should continue. If the system supports system restore, or the user chooses to continue, a restore point is set and the setup tasks are completed.


System.TerminateProcess Examples

System.TerminateProcess

boolean System.TerminateProcess (

number ProcessID )

Example 1

terminate_status = System.TerminateProcess(3444);

Terminates the process whose process ID is 3444 and stores the result in the variable "terminate_status."

Example 2

instances_of_file = 0;
file_to_check_for = "dummy.exe"; --have all lowercase
processes = System.EnumerateProcesses();

for j, file_path in pairs(processes) do
file = String.SplitPath(file_path);
if (String.Lower(file.Filename..file.Extension)) == file_to_check_for then
System.TerminateProcess(j);
end
end

Terminates all processes that were spawned by the executable "dummy.exe."


System.UnregisterActiveX Examples

System.UnregisterActiveX

System.UnregisterActiveX (

string Filename )

Example 1

System.UnregisterActiveX(_SystemFolder .. "\\mycontrol.ocx");

Unregisters the ActiveX control named "mycontrol.ocx" located in the user's system folder.

Note: _SystemFolder is a built-in variable that contains the path to the user's "System" folder.


System.UnregisterFont Examples

System.UnregisterFont

System.UnregisterFont (

string Filename,

string Fontname,

boolean Permanent = true )

Example 1

fonts_dir = Shell.GetFolder(SHF_FONTS); -- Gets the path to the user's Font directory.
System.UnregisterFont(fonts_dir .. "\\myfont.ttf", "Crazy Font", true);

The first line uses the Shell.GetFolder action to get the path to the user's Font directory and stores it's path in the variable "fonts_dir." The second action permanently unregisters the font file named "myfont.ttf" on the user's local system with the name "Crazy Font."


Table.Concat Examples

Table.Concat

string Table.Concat (

table SourceTable,

string Separator,

number Start = 1,

number End = TABLE_ALL )

Example 1

target_table = {"John","Mary","George","Sally"}; --Creates a table whose values are 4 strings.
table_values = Table.Concat(target_table, ";;", 2, 3);

Creates a string by concatenating target_table's values starting at position 2 and ending at position 3. In this example the string "Mary;;George" will be created and stored in the variable "table_values."

Example 2

target_table = {"John","Mary","George","Sally"}; --Creates a table whose values are 4 strings.
table_values = Table.Concat(target_table, ";;", 1, TABLE_ALL);

Creates a string by concatenating all of target_table's values. In this example the string "John;;Mary;;George;;Sally" will be created and stored in the variable "table_values."


Table.Count Examples

Table.Count

number Table.Count (

table SourceTable )

Example 1

target_table = {"John","Mary","George","Sally"}; --Creates a table whose values are 4 strings.
count = Table.Count(target_table);

Gets the total number of items in the table called "target_table" and stores it in the variable "count." In this example, the number 4 will be returned.


Table.Insert Examples

Table.Insert

Table.Insert (

table SourceTable,

number Position,

variant Value )

Example 1

Debug.ShowWindow(true);
target_table = {"One","Two","Three"}; --Creates a table whose values are 3 strings.
Table.Insert(target_table, 2, "Four");
for x,y in pairs(target_table) do
Debug.Print("Index "..x.." = "..y.."\r\n");
end

Inserts the string "Four" into index 2 of the table called "target_table." For this example, a loop has been created to output the new contents of the table to the debug window. The output would be the following:

Index 1 = One
Index 2 = Four
Index 3 = Two
Index 4 = Three

Tip: You can copy the action code from these examples and paste it into the Action Editor to test it.

Example 2

Debug.ShowWindow(true);
target_table = {"One","Two","Three"}; --Creates a table whose values are 3 strings.
Table.Insert(target_table, Table.Count(target_table)+1, "Four");
for x,y in pairs(target_table) do
Debug.Print("Index "..x.." = "..y.."\r\n");
end

Inserts the string "Four" into index 4 of the table called "target_table." In this example the Table.Count action is used to get the number of items in the table so the new item can be inserted at the end. Here is what would be printed in the debug window:

Index 1 = One
Index 2 = Two
Index 3 = Three
Index 4 = Four


Table.Remove Examples

Table.Remove

variant Table.Remove (

table SourceTable,

number Position )

Example 1

Debug.ShowWindow(true);
mytable = {"One", "Two", "Three", "Four"} ; --Creates a table whose values are 4 strings.
removed_item = Table.Remove(mytable, 2);
for x,y in pairs(mytable) do
Debug.Print("Index "..x.." = "..y.."\r\n");
end
Debug.Print("Removed Item ="..removed_item);

Removes the item at index 2 from the table called "mytable" and stores it's value in the variable "removed_item." In this example, the new contents of the table are printed to the debug window along with the value of the removed item. Here is what would be printed in the debug window:

Index 1 = One
Index 2 = Three
Index 3 = Four
Removed Item =Two

Tip: You can copy the action code from this example and paste it into the Action Editor to test it.


Table.Sort Examples

Table.Sort

Table.Sort (

table SourceTable,

function Compare = nil )

Example 1

Debug.ShowWindow(true);
MyTable = {46,102,12,85};
Table.Sort(MyTable, nil)
for x,y in pairs(MyTable) do
Debug.Print(y.."\r\n");
end

Sorts the items in "MyTable" in ascending order and then prints the sorted table to the debug window. Here is what would be printed in the debug window:

12
46
85
102

Example 2

function sorter(v1,v2)
if (v1 > v2)then
return true;
else
return false;
end
end

Debug.ShowWindow(true);
MyTable = {"Hockey","Baseball","Football", "Soccer"};
Table.Sort(MyTable, sorter);
for x,y in pairs(MyTable) do
Debug.Print(y.."\r\n");
end

The first block of code defines a function "sorter" that compares two values and returns true if the first item is greater than the second item. The "sorter" function is then used in the Table.Sort action to sort the items in descending alphabetical order (z - a). Here is what would be printed in the debug window:

Soccer
Hockey
Football
Baseball


TextFile.ReadToString Examples

TextFile.ReadToString

string TextFile.ReadToString (

string Filename )

Example 1

text_contents = TextFile.ReadToString(_SourceFolder .. "\\Information.txt");

Reads the contents of the file "Information.txt" and stores the string in the variable text_contents.

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 2

-- Read the contents of a text file into a string.
contents = TextFile.ReadToString("C:\\MyFile.txt");

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Replace every occurrence of the string "Robert" with the string "Adam".
new_contents = String.Replace(contents, "Robert", "Adam", true);

-- Write out the modified contents of the text file.
TextFile.WriteFromString("C:\\MyFile.txt", new_contents, false);

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of the file "MyFile.txt" and stores the string in the variable "contents." Every occurrence of the string "Robert" in "contents" is replaced with the string "Adam" and then written back to the text file "MyFile.txt".


TextFile.ReadToTable Examples

TextFile.ReadToTable

table TextFile.ReadToTable (

string Filename )

Example 1

text_table = TextFile.ReadToTable(_SourceFolder .. "\\Information.txt");

Reads the contents of the file "Information.txt" and stores each line in the table "text_table."

Note: _SourceFolder is a built-in variable that contains the path to the folder where the setup.exe file is located.

Example 2

-- Read the contents of a text file to a table.
text_contents = TextFile.ReadToTable("C:\\MyFile.txt");

-- Get the error code of the last action.
error = Application.GetLastError();

-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Remove the second item in the table (second line in the text file).
Table.Remove(text_contents, 2);

-- Write out the modified text file.
TextFile.WriteFromTable("C:\\MyFile.txt", text_contents, false);

-- Get the error code of the last action.
error = Application.GetLastError();
-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of a text file to a table. The second table entry (second line) is then removed and written back to the text file overwriting its current contents.


TextFile.WriteFromString Examples

TextFile.WriteFromString

TextFile.WriteFromString (

string Filename,

string Text,

boolean Append = false )

Example 1

TextFile.WriteFromString(_TempFolder .. "\\Information.txt", "Blue", false);

Writes the string "Blue" to the file "Information.txt" located in the user's temporary folder. The file's current contents will be overwritten.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

TextFile.WriteFromString(_TempFolder .. "\\Information.txt", "Blue", true);

Appends the string "Blue" to the current contents of the file "Information.txt" located in the user's temporary folder.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 3

-- Read the contents of a text file into a string.
contents = TextFile.ReadToString("C:\\MyFile.txt");

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Replace every occurrence of the string "Robert" with the string "Adam".
new_contents = String.Replace(contents, "Robert", "Adam", true);

-- Write out the modified contents of the text file.
TextFile.WriteFromString("C:\\MyFile.txt", new_contents, false);

-- Check the error code of the last example.
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of the file "MyFile.txt" and stores the string in the variable "contents." Every occurrence of the string "Robert" in "contents" is replaced with the string "Adam" and then written back to the text file "MyFile.txt".


TextFile.WriteFromTable Examples

TextFile.WriteFromTable

TextFile.WriteFromTable (

string Filename,

table Table,

boolean Append = false )

Example 1

TextFile.WriteFromTable(_TempFolder .. "\\Information.txt", table_input, false);

Writes out the contents of the "table_input" table to the file "Information.txt" located in the user's temporary folder. The table consists of one line of text per table item. Any current text within "Information.txt" will be overwritten.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

TextFile.WriteFromTable(_TempFolder .. "\\Information.txt", table_input, true);

Appends the contents of the "table_input" table to the file "Information.txt" located in the user's temporary folder. The table consists of one line of text per table item.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 3

-- Read the contents of a text file to a table.
text_contents = TextFile.ReadToTable("C:\\MyFile.txt");

-- Get the error code of the last action.
error = Application.GetLastError();

-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
-- Remove the second item in the table (second line in the text file).
Table.Remove(text_contents, 2);

-- Write out the modified text file.
TextFile.WriteFromTable("C:\\MyFile.txt", text_contents, false);

-- Get the error code of the last action.
error = Application.GetLastError();
-- If an error occurred, display the error code message.
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end
end

Reads the contents of a text file to a table. The second table entry (second line) is then removed and written back to the text file overwriting its current contents.


UninstallData.AddItem Examples

UninstallData.AddItem

UninstallData.AddItem (

number ItemType,

table ItemData )

Example 1

UninstallData.AddItem(UNINDATA_MAIN, {Name="RegInfoPath", Value="c:\\some_folder\\reg_info.enc"});

Adds the item "RegInfoPath" to the uninstall configuration file with a path as the value into the UNINDATA_MAIN section of the file.

Example 2

UninstallData.AddItem(nItemType, tItemData);

Adds the values contained in the table "tItemData" into the section contained in value "nItemType" to the uninstall configuration file.

Example 3

-- Assign table values
tbl_values = {
Filename = SessionVar.Expand("%SourceFolder%\\globals.dll"),
DecrementUsageCount = true,
UnregisterCOM = false,
UnregisterFont = false,
BackupFile = SessionVar.Expand("%AppFolder%\\Backups\\globals_dll.bak")
}

-- Add a Data item to the uninstall data file based on the above table values
UninstallData.AddItem(UNINDATA_FILES, tbl_values);

Adds the file globals.dll to the uninstall data file, along with the location of the backup file.

Note: You must manually back up the file, setup factory does not automatically do this for you.


UninstallData.GetConfigurationFile Examples

UninstallData.GetConfigurationFile

string UninstallData.GetConfigurationFile (

)

Example 1

sUniFile = UninstallData.GetConfigurationFile();

Stores the complete path to the uninstall configuration file in the variable "sUniFile".


UninstallData.GetItem Examples

UninstallData.GetItem

table UninstallData.GetItem (

number ItemType,

string Identifier )

Example 1

tItemData = UninstallData.GetItem(UNINDATA_FOLDERS, sFolderPath);

Gets the details of the folder path stored in the string "sFolderPath", and stores them in the table "tItemData".

Example 2

tSessionVars = UninstallData.GetItemList(UNINDATA_SESSIONVARS);
sOutput = "";

for nIndex, sName in pairs(tSessionVars) do
tDetails = UninstallData.GetItem(UNINDATA_SESSIONVARS, sName);
sOutput = sOutput .. tDetails.Name .. ": " .. tDetails.Value .. "\r\n";
end

TextFile.WriteFromString("C:\\SessionVariables.txt", sOutput, false);

Gets a list of the session variables stored in the uninstall configuration file. Each of these session variables, and their stored values are stored in the string sOutput, and written out to a text file.

Example 3

-- Get the data for file globals.dll from the uninstall data file
Item_Data = UninstallData.GetItem(UNINDATA_FILES, SessionVar.Expand("%SourceFolder%\\globals.dll"));

if Item_Data.Backup ~= "" then
-- Copy the backed up file to the original location
File.Copy(Item_Data.Backup, SessionVar.Expand("%SourceFolder%\\globals.dll"), false, true, false, true, nil);
-- Delete the backed up file
File.Delete(Item_Data.Backup, false, false, true, nil);
end

Restores the backed-up version of the globals.dll if it was backed up. If it was not backed up, nothing happens.


UninstallData.GetItemList Examples

UninstallData.GetItemList

table UninstallData.GetItemList (

number ItemType )

Example 1

tItemList = UninstallData.GetItemList(UNINDATA_FILES);

Gets a list of all of the files referenced in the uninstall configuration file and stores it in table "tItemList".

Example 2

tSessionVars = UninstallData.GetItemList(UNINDATA_SESSIONVARS);
sOutput = "";

for nIndex, sName in pairs(tSessionVars) do
tDetails = UninstallData.GetItem(UNINDATA_SESSIONVARS, sName);
sOutput = sOutput .. tDetails.Name .. ": " .. tDetails.Value .. "\r\n";
end

TextFile.WriteFromString("C:\\SessionVariables.txt", sOutput, false);

Gets a list of the session variables stored in the uninstall configuration file. Each of these session variables, and their stored values are stored in the string sOutput, and written out to a text file.


UninstallData.RemoveItem Examples

UninstallData.RemoveItem

UninstallData.RemoveItem (

number ItemType,

string Identifier )

Example 1

UninstallData.RemoveItem(UNINDATA_SUPPORTFILES, sFilename);

Removes the support file referenced in the value "sFilename" from the uninstall configuration file.

Example 2

tResults = UninstallData.GetItemList(UNINDATA_SCRIPTS);

for nIndex, sIdentifier in pairs(tResults) do
UninstallData.RemoveItem(UNINDATA_SCRIPTS, sIdentifier);
end

Removes all items from the 'scripts' section of the uninstall configuration file.


UninstallData.SetConfigurationFile Examples

UninstallData.SetConfigurationFile

UninstallData.SetConfigurationFile (

string Filename )

Example 1

UninstallData.SetConfigurationFile(_WindowsFolder .. "\\Uninstall_Info\\config.xml");

Sets the uninstall configuration file to be created in the user's Windows folder, in the sub-directory "Uninstall_Info".

Example 2

UninstallData.SetConfigurationFile(sConfigFile);

Sets the uninstall configuration file to be created in the location referenced in the string "sConfigFile".


Window.Close Examples

Window.Close

Window.Close (

number WndHandle,

number Method = CLOSEWND_SENDMESSAGE )

Example 1

Window.Close(app_handle, CLOSEWND_SENDMESSAGE);

Sends a close message to the program whose window handle is stored in the variable "app_handle."

Example 2

Window.Close(app_handle, CLOSEWND_TERMINATE);

Terminates the process of the program whose window handle is stored in the variable "app_handle."

Example 3

-- Get the titles and window handles of all open windows.
windows = Window.EnumerateTitles();

-- A variable containing text in the title you want to search for.
window_name = "Notepad";

-- Loop through the table of windows.
for handle, title in pairs(windows) do

-- Check if the window title has the target text.
result = String.Find(title, window_name, 1, false);

-- if the string was found in the title, send the window a close message.
if (result ~= -1) then
Window.Close(handle, CLOSEWND_SENDMESSAGE);
end
end

Finds all open windows with the string "Notepad" in the title and sends each of them a close message.


Window.EnumerateProcesses Examples

Window.EnumerateProcesses

table Window.EnumerateProcesses (

boolean TopLevel = true )

Example 1

open_processes = Window.EnumerateProcesses();

Gets the window handles and executable file paths for every process that is currently running and stores them in a table named open_processes.

Example 2

instances_of_file = 0;
file_to_check_for = "setup.exe"; --have all lowercase
processes = Window.EnumerateProcesses();

for j, file_path in pairs(processes) do
file = String.SplitPath(file_path);
if (String.Lower(file.Filename..file.Extension)) == file_to_check_for then
instances_of_file = instances_of_file + 1;
end
end

if instances_of_file > 1 then
Window.Hide(Application.GetWndHandle());
Dialog.Message("Error", "Setup already running: code: already running");
Window.Close(Application.GetWndHandle(), CLOSEWND_TERMINATE);
else
Window.Show(Application.GetWndHandle());
end

As an example, let us assume that you want to run your program, only if there is not another setup.exe running on the system. To accomplish this, use the Window.EnumerateProcesses action, and check every process against the filename setup.exe.


Window.EnumerateTitles Examples

Window.EnumerateTitles

table Window.EnumerateTitles (

boolean TopLevel = true )

Example 1

all_titles = Window.EnumerateTitles();

Gets the window handles and titles of all of the open windows on the user's system and stores them in a table called "all_titles."

Example 2

-- Get the titles and window handles of all open windows.
windows = Window.EnumerateTitles();

-- A variable containing text in the title you want to search for.
window_name = "Notepad";

-- Loop through the table of windows.
for handle, title in pairs(windows) do

-- Check if the window title has the target text.
result = String.Find(title, window_name, 1, false);

-- if the string was found in the title, send the window a close message.
if (result ~= -1) then
Window.Close(handle, CLOSEWND_SENDMESSAGE);
end
end

Finds all open windows with the string "Notepad" in the title and sends each of them a close message.


Window.GetPos Examples

Window.GetPos

table Window.GetPos (

number WndHandle )

Example 1

Acro_Pos = Window.GetPos(Acrobat_Handle);

Gets the current X, Y coordinates of the program whose window handle is stored in the variable "Acrobat_Handle" and stores the results in a table called "Acro_Pos." These values can be accessed by referencing Acro_Pos.X and Acro_Pos.Y.

Example 2

tPos = Window.GetPos(Application.GetWndHandle());

Gets the current X, Y coordinates of the installation window and stores the results in a table called "tPos." These values can be accessed by referencing tPos.X and tPos.Y. This example uses the Application.GetWndHandle action to get the installation's window handle.


Window.GetSize Examples

Window.GetSize

table Window.GetSize (

number WndHandle )

Example 1

app_size = Window.GetSize(app_handle);

Gets the pixel dimensions of the window whose handle is stored in "app_handle" and stores the width and height values in the "app_size" table. The dimensions can be accessed by referencing app_size.Width and app_size.Height.

Example 2

tWindowSize = Window.GetSize(Application.GetWndHandle());

Gets the pixel dimensions of the installation window and stores the width and height values in the "tWindowSize" table. The dimensions can be accessed by referencing tWindowSize.Width and tWindowSize.Height. This action uses the Application.GetWndHandle to get the installation's window handle.


Window.Hide Examples

Window.Hide

Window.Hide (

number WndHandle )

Example 1

Window.Hide(app_handle);

Hides the window of a program whose window handle is stored in the variable "app_handle."

Example 2

-- Get the installation's window handle.
handle = Application.GetWndHandle();

-- Hide the installation window.
Window.Hide(handle);

-- Sleep for 3 seconds.
Application.Sleep(3000);

-- Show the installation window.
Window.Show(handle);

Gets the numeric window handle for the installation window and stores it in the variable "handle." The window handle is then used to hide the window for 3 seconds.


Window.Maximize Examples

Window.Maximize

Window.Maximize (

number WndHandle )

Example 1

Window.Maximize(app_handle);

Maximizes the window of a program whose window handle is stored in the variable "app_handle."


Window.Minimize Examples

Window.Minimize

Window.Minimize (

number WndHandle )

Example 1

Window.Minimize(app_handle);

Minimizes the window of a program whose window handle is stored in the variable "app_handle."


Window.Restore Examples

Window.Restore

Window.Restore (

number WndHandle )

Example 1

Window.Restore(app_handle);

Restores the window of a program whose window handle is stored in the variable "app_handle."


Window.SetOrder Examples

Window.SetOrder

Window.SetOrder (

number WndHandle,

number InsertAfter )

Example 1

Window.SetOrder(app_handle, after_me);

Sets the window whose handle is "app_handle" to be above the window whose handle is "after_me" in Z-Order.

Example 2

Window.SetOrder(app_handle, HWND_TOP);

Set's the window whose handle is stored in "app_handle" to have the highest Z-Order.


Window.SetPos Examples

Window.SetPos

Window.SetPos (

number WndHandle,

number X,

number Y )

Example 1

Window.SetPos(app_handle, 100, 150);

Sets a program window's X coordinate to 100 pixels and the Y coordinate to 150. The program's window handle is passed to the action through the variable "app_handle."

Example 2

Window.SetPos(app_handle, 0, 0);

Sets a program window's X coordinate to 0 and the Y coordinate to 0. The window will be moved to the upper left hand corner of the page from it's current position. The program's window handle is passed to the action through the variable "app_handle."


Window.SetSize Examples

Window.SetSize

Window.SetSize (

number WndHandle,

number Width,

number Height )

Example 1

Window.SetSize(app_handle, 100, 150);

Sets a program's window to a width of 100 pixels and a height of 150 pixels. The program's window handle is passed to the action through the variable "app_handle."


Window.SetText Examples

Window.SetText

Window.SetText (

number WndHandle,

string Text )

Example 1

Window.SetText(app_handle, "Mystery Application");

Sets a program's title bar text to the string "Mystery Application." The program's window handle is passed to the action through the variable "app_handle." This new text will display in the program's title bar and task bar.


Window.Show Examples

Window.Show

Window.Show (

number WndHandle )

Example 1

Window.Show(app_handle);

Shows the window of a program whose window handle is stored in the variable "app_handle."

Example 2

-- Get the installation's window handle.
handle = Application.GetWndHandle();

-- Hide the installation's window.
Window.Hide(handle);

-- Sleep for 3 seconds.
Application.Sleep(3000);

-- Show the installation's window.
Window.Show(handle);

Gets the numeric window handle for the application window and stores it in the variable "handle." The window handle is then used to hide the window for 3 seconds.


XML.Count Examples

XML.Count

number XML.Count (

string XMLPath,

string ElementName )

Example 1

-- This example assumes the sample XML is already loaded into memory.
-- Count the total number of elements in "database".
count = XML.Count("database", "*");

-- Display the count in a dialog message if no errors occurred.
if (count ~= -1) then
Dialog.Message("Count", "There are "..count.." elements in the database.");
end

Counts the total number of elements in "database" and shows the result in a dialog message.

Example 2

-- This example assumes the sample XML is already loaded into memory.
-- Count the number of "phone" elements in the first customer element.
count = XML.Count("database/customer", "phone");

-- Display the count in a dialog message if no errors occurred.
if (count ~= -1) then
Dialog.Message("Count", "There are "..count.." phone elements in the first customer element.");
end

Counts the number of "phone" elements in the first customer element and shows the result in a dialog message.


XML.GetAttribute Examples

XML.GetAttribute

string XML.GetAttribute (

string XMLPath,

string AttributeName )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Get the value of the first customer id attribute.
attribute_result = XML.GetAttribute("database/customer", "id");

-- Perform some error checking.
error = Application.GetLastError();
if (error == 0) then
Dialog.Message("Attribute Value", "The first customer id is: "..attribute_result);
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the value of the first customer id attribute and displays it in a dialog message.

Example 2

-- This example assumes the sample XML is already loaded into memory.

-- Get the value of the second customer product attribute.
attribute_result = XML.GetAttribute("database/customer:2", "product");

-- Perform some error checking.
error = Application.GetLastError();
if (error == 0) then
Dialog.Message("Attribute Value", "The second customer's product is: "..attribute_result);
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the value of the second customer product attribute and displays it in a dialog message.


XML.GetAttributeNames Examples

XML.GetAttributeNames

table XML.GetAttributeNames (

string XMLPath )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the names of the customer element's attributes.
customer_attributes = XML.GetAttributeNames("database/customer");

-- Perform some error checking.
error = Application.GetLastError();
if (error == 0) then
Dialog.Message("Element Attributes", "The two attribute names are: \r\n\r\n"..customer_attributes[1].."\r\n"..customer_attributes[2]);
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the names of the customer element's attributes and displays them in a dialog message.


XML.GetElementNames Examples

XML.GetElementNames

table XML.GetElementNames (

string XMLPath,

boolean FullPaths = false,

boolean IncludeIndices = false )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the names of all of the child elements of address_info.
tbChild_elements = XML.GetElementNames("database/customer/address_info", false, false);

-- Perform some error checking.
error = Application.GetLastError();
-- If no errors occurred...
if (error == 0) then
if (tbChild_elements ~= nil) then

-- Convert the table to a return/newline delimited string to display in a dialog.
strChild_elements = Table.Concat(tbChild_elements, "\r\n", 1, TABLE_ALL);

-- Display a dialog message containing all child names.
Dialog.Message("Child Element Names", strChild_elements);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the names of all of the child elements of "addresss_info" and shows them in a dialog message.


XML.GetElementXML Examples

XML.GetElementXML

string XML.GetElementXML (

string XMLPath )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- get the raw XML text of the 2nd customer element
strCustomerXML = XML.GetElementXML("database/customer:2");

error = Application.GetLastError();
if (error ~= XML.OK) then
Dialog.Message("Error", _tblErrorMessages[error]);
end

-- get the customer's name from the XML
strCustomerName = XML.GetValue("database/customer:2/first_name") ..
XML.GetValue("database/customer:2/last_name");

-- save the customer record as a separate XML document in C:\customer_records
TextFile.WriteFromString( "C:\\customer_records\\"..strCustomerName..".xml"
, strCustomerXML
, false );

Gets the customer's name from the XML and then saves the customer record as a separate XML document.


XML.GetValue Examples

XML.GetValue

string XML.GetValue (

string XMLPath )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Gets the value in database/customer/first_name.
customer_name = XML.GetValue("database/customer/first_name");

-- If a value was returned, display it in a dialog message.
if (customer_name ~= "") then
Dialog.Message("Value","The customer's first name is "..customer_name);
else
Dialog.Message("Problem", "The customer name could not be located.");
end

Gets the value in "/database/customer/first_name" and shows it in a dialog message.

Example 2

-- This example assumes the sample XML is already loaded into memory.

-- Gets the second customer's second phone number.
customer_phone = XML.GetValue("database/customer:2/phone:2");

-- If a value was returned, display it in a dialog message.
if (customer_phone ~= "") then
Dialog.Message("Value","The customer's second phone number is "..customer_phone);
else
Dialog.Message("Problem", "The telephone number could not be located.");
end

Gets the second customer's second phone number and shows it in a dialog message.


XML.GetXML Examples

XML.GetXML

string XML.GetXML (

)

Example 1

-- Load an XML file into memory.
XML.Load(_TempFolder.."\\Sample2.xml");

-- Check if an error was returned.
error = Application.GetLastError();
-- If no errors occurred...
if (error == 0) then
-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
Dialog.Message("XML contents",strXML);
else
Dialog.Message("Error", _tblErrorMessages[error]);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Loads an XML file into memory, gets that XML as a string and then shows it in a dialog message.


XML.InsertXML Examples

XML.InsertXML

XML.InsertXML (

string XMLPath,

string Text,

number InsertionMode )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- we'll use the debug window to show what's happening
Debug.ShowWindow(true);

-- get the raw XML for the first customer's address_info and display it in the debug window
strAddress = XML.GetElementXML("database/customer/address_info");

Debug.Print(strAddress.."\r\n\r\n");
-- insert a planet element right after the country element
Debug.Print("Inserting planet...\r\n");

XML.InsertXML("database/customer/address_info/country", "<planet>Earth</planet>", XML.INSERT_AFTER);

-- check for errors
error = Application.GetLastError();
-- If an error occurred, display the error message.
if (error == 0) then
Debug.Print("Planet inserted.\r\n\r\n");
else
Debug.Print("Error: ".. _tblErrorMessages[error] .. "\r\n");
end

-- get the raw XML again and display it in the debug window to show what has changed
strAddress = XML.GetElementXML("database/customer/address_info");
Debug.Print(strAddress.."\r\n\r\n");

Gets the raw XML for the first customer's address_info, inserts some new information in it and then gets the raw XML again to show the changes. All output is shown in the debug window.


XML.Load Examples

XML.Load

XML.Load (

string Filename )

Example 1

-- Load an XML file into memory.
XML.Load(_TempFolder.."\\Sample2.xml");

-- Check whether an error occurred
error = Application.GetLastError();
-- If no errors occurred...
if (error == XML.OK) then
-- get the current XML document as a string
strXML = XML.GetXML();

-- if no errors occurred, display the XML in a popup dialog
error = Application.GetLastError();
if (error == XML.OK) then
Dialog.Message("XML contents",strXML);
else
Dialog.Message("Error", _tblErrorMessages[error]);'
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Loads an XML file into memory, gets that XML as a string, and then shows it in a dialog message.


XML.RemoveAttribute Examples

XML.RemoveAttribute

XML.RemoveAttribute (

string XMLPath,

string AttributeName )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

if (strXML ~= "") then
Dialog.Message("Original XML contents",strXML);
end

-- Removes the "product" attribute from the first customer.
XML.RemoveAttribute("database/customer", "product");

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded(modified) XML in a string.
strXML = XML.GetXML();
if (strXML ~= "") then
Dialog.Message("Modified XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the contents of the currently loaded XML as a string and first shows it in a dialog message. The "product" attribute is then removed from the first customer and the new XML is then shown in a dialog message.


XML.RemoveElement Examples

XML.RemoveElement

XML.RemoveElement (

string XMLPath )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

if (strXML ~= "") then
Dialog.Message("Original XML contents",strXML);
end

-- Removes the address info element from the first customer entry.
XML.RemoveElement("database/customer/address_info");

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded (modified) XML in a string.
strXML = XML.GetXML();
if (strXML ~= "") then
Dialog.Message("Modified XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the currently loaded XML as a string and first shows it in a dialog message. Next, the address info element is removed from the first customer entry and the XML is reloaded as a string. The final XML is then shown in a dialog message.


XML.Save Examples

XML.Save

XML.Save (

string Filename )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Saves the currently loaded XML to a file in the user's temp folder.
XML.Save(_TempFolder.."\\Sample_XML_Save.xml");

-- Check to see if any errors occurred.
error = Application.GetLastError();
if (error ~= 0) then
Dialog.Message("Error", _tblErrorMessages[error]);
end

Saves the currently loaded XML to a file in the user's temp folder.


XML.SetAttribute Examples

XML.SetAttribute

XML.SetAttribute (

string XMLPath,

string AttributeName,

string AttributeValue )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

if (strXML ~= "") then
Dialog.Message("Original XML contents",strXML);
end

-- Changes the second customer element's attribute id to "9999".
XML.SetAttribute("database/customer:2", "id", "new id");

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded (modified) XML in a string.
strXML = XML.GetXML();
if (strXML ~= "") then
Dialog.Message("Modified XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the currently loaded XML as a string and shows it in a dialog message. Next, the second customer element's attribute id is changed to "9999" and the new XML is shown in a dialog message.


XML.SetValue Examples

XML.SetValue

XML.SetValue (

string XMLPath,

string Value,

boolean WriteCDATA = false )

Example 1

-- This example assumes the sample XML is already loaded into memory.

-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

if (strXML ~= "") then
Dialog.Message("Original XML contents",strXML);
end

-- Sets the first customer element's company name to "New Company Name".
XML.SetValue("database/customer/company", "New Company Name");

-- See if any errors occurred. If no errors occurred, display the string.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded (modified) XML in a string.
strXML = XML.GetXML();
if (strXML ~= "") then
Dialog.Message("Modified XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Gets the currently loaded XML as a string and shows it in a dialog message. Next the first customer element's company name is set to "New Company Name" and the new XML is shown in a dialog message.


XML.SetXML Examples

XML.SetXML

XML.SetXML (

string Text )

Example 1

-- Sets the currently loaded XML document to the text from a string.
XML.SetXML("MyValue1MyValue2");

-- Check if any errors occurred setting the XML.
error = Application.GetLastError();
if (error == 0) then
-- Return the currently loaded XML in a string.
strXML = XML.GetXML();

-- Display the XML contents in a dialog.
if (strXML ~= "") then
Dialog.Message("XML contents",strXML);
end
else
Dialog.Message("Error", _tblErrorMessages[error]);
end

Sets the currently loaded XML document to the text from a string and then shows its contents in a dialog message.


New Build Configuration

Build Settings

New Build Configuration

New build configuration name:

The name you want to use for your new build configuration.

Copy defaults from:

The default configuration settings you want to start with in your new build configuration. One of the current build configurations can be selected from the dropdown.


Edit Multiple Install Order Values

Multiple File Properties

Edit Multiple Install Order Values

Modify mode:

The mode you want to use to modify the current property. Choose from:

Don't Change

Don't change the current property for any of the selected files.

Change All

Change the current property for all selected files.

Change all to:

The value to change the current property to for all currently selected files.

Add to All

Add a value to the current install order property for all selected files.

Amount to add:

The value you want to add to the current install order property for all selected files.

Subtract from All

Subtract a value from the current install order property for all selected files.

Amount to subtract:

The value you want to subtract from the current install order property for all selected files.

Renumber

Renumber the install order values for all selected files.

Start at:

The number to start the renumbering from.

Step size:

The amount you want to increment each value by.

Show original values

Show the original values of the properties for all selected files in the information window.

Preview changes

Show a preview of the proposed property changes for all selected files in the information window.


Edit Multiple Values

Multiple File Properties

Edit Multiple Values

Modify mode:

The mode you want to use to modify the current property. Choose from:

Don't Change

Don't change the current property for any of the selected files.

Change All

Change the current property for all selected files.

Change all to:

The value to change the current property to for all currently selected files.

Append to All

Append text to the current property of all selected files.

Text to append:

The text you want to append to the current property of all selected files.

Prepend to All

Prepend text to the current property of all selected files.

Text to prepend:

The text you want to prepend to the current property of all selected files.

Search and Replace

Perform a search and replace on the text of the current property for all selected files.

Case sensitive

Perform a case sensitive search and replace.

Search for:

The text you want to search for.

Replace with:

The text you want to replace the Search for text with.

Show original values

Show the original values of the properties for all selected files in the information window.

Preview changes

Show a preview of the proposed property changes to all selected files in the information window.


Filter Properties

Overview

Name:

The name of the current filter.

Property:

The file property you want to use when configuring the filter setting. You can click the drop down to select a file property. These properties include all of the possible columns that can be shown in the Setup Factory program window. Each column can be shown or hidden by selecting View > Columns from the program menu.

Rule:

The rule you want to use for the filter. The following rules are available when you click the drop down to select a rule:

RULE | DESCRIPTION
Does Not Match Pattern | The Property value of the file does not match the pattern specified as the Criteria.
Equal To | The Property value of the file is equal to the value specified as the Criteria.
Greater Than | The Property value of the file is greater than the value specified as the Criteria.
Greater Than or Equal To | The Property value of the file is greater than or equal to the value specified as the Criteria.
Is Empty | The Property value of the file is empty. (This rule does not use the Criteria value.)
Is Not Empty | The Property value of the file is not empty. (This rule does not use the Criteria value.)
Less Than | The Property value of the file is less than the value specified as the Criteria.
Less Than or Equal To | The Property value of the file is less than or equal to the value specified as the Criteria.
Matches Pattern | The Property value of the file matches the pattern specified as the Criteria.
Not Equal To | The Property value of the file is not equal to the value specified as the Criteria.

Criteria:

The criteria you want the selected rule to be applied to. The value of a criteria can either be a single value such as a string, a number or boolean value such as true or false. If the criteria value is a number, a numeric comparison will be used. If the value is a string, a string comparison will be used. If the value is a version number, a version comparison will be used.

When either Does Not Match Pattern or Matches Pattern are chosen as the rule to be applied, the following pattern matching characters can be used:

PATTERN | DESCRIPTION
* | Any combination of characters. For example, a*le - matches ale, apple, angle, etc.
? | Any single character. For example, s?n - matches sun, son, sin, s4n, etc.
[character - character] | Character set matching per character. For example, using the character set [A-E] will ensure that a single character in the Property value is within the range, A to E inclusive. The character range must be specified in uppercase. Character sets can also include a list of characters. For example, [ABC] will ensure that the character is either A, B, or C. You can also specify characters as well as a range in the pattern. For example, [ABCF-RZ] will match A, B, or C, the characters in the range F-R or Z.

Example 1:

To filter your file list so it only displays executable files, the filter properties would look like the following:

Property: File Extension
Rule: Equal To
Criteria: exe

When this filter is applied, only files with a ".exe" extension will be shown in the Setup Factory file list.

Example 2:

To filter your file list so it only displays files that have their Register COM Interfaces option selected (files that require registration) the filter properties would look like the following:

Property: Register COM
Rule: Equal To
Criteria: true

The value true is used as the Criteria because that file property is controlled by a check box that has either a true or false state.

When this filter is applied, only files that are designated to be registered as a COM interface will be shown in the Setup Factory file list.

Example 3:

To filter your file list so it only displays files that contain the string "Help" in their name, the filter properties would look like the following:

Property: Filename
Rule: Matches Pattern
Criteria: *Help*

When this filter is applied, only files that contain the string "Help" in their name will be shown in the Setup Factory file list.

Example 4:

To filter your file list so it only displays files that contain a file size that is less than 1MB (1048576 bytes), the filter properties would look like the following:

Property: Size
Rule: Less Than or Equal To
Criteria: 1048576

When this filter is applied, only files whose size is less than 1MB (1048576 bytes) will be shown in the Setup Factory file list.

Example 5:

To filter your file list so it only displays files whose file extensions contain characters between A-E, the filter properties would look like the following:

Property: Filename
Rule: Matches Pattern
Criteria: *.[A-E][A-E][A-E]

When this filter is applied, only files whose extensions contain characters between A-E will be shown in the Setup Factory file list.

Example 6:

To filter your file list so it only displays files whose dates are later than January 31st 2003, the filter properties would look like the following:

Property: Date
Rule: Greater Than
Criteria: 2003-01-31

When this filter is applied, only files whose dates are later than January 31st 2003 will be shown in the Setup Factory file list.

Note: File dates must be in the format YYYY-MM-DD.


Add New Language

Overview

Adding a new language to your setup means that you want the install to detect that language and use its corresponding language message file and translated screens for the setup.

Available languages:

A list of the languages you can detect in your install. You can select the language you wish to support in your setup and click OK.

Note: Not all languages contain pre-made message files and translated screens. Languages that are currently installed will show a "*" character beside its name. All available language modules can be downloaded from the Indigo Rose web site, www.indigorose.com. In the case where one is not available, it is up to the developer to create the translated message file (.XML) and screens, or use the default language's message file and screens.


Callback Function Examples

Miscellaneous

Contents Callback Functions Example

Create a Custom Callback Function

If you have an action requiring a status dialog, but the standard status dialog (StatusDlg) is not sufficient, it is possible to create a custom callback function for those actions requiring one.

As an example, we will use a custom callback function to show the progress of a file download:

--ShowStatusWindow shows the status window, and sets the title
function ShowStatusWindow()
-- Show the Status Dialog
StatusDlg.Show(MB_ICONINFORMATION, false);
-- Show the cancel button
StatusDlg.ShowCancelButton(true, "Stop Download");
end

--DownloadStatus is the callback function to be used.
function DownloadStatus (BytesRead, FileSize, TransferRate, SecondsLeft, SecondsLeftFormat, Message)
-- Set the status meter's range
StatusDlg.SetMeterRange(0, Math.Floor(FileSize/1024));
-- Set the meter position
StatusDlg.SetMeterPos(Math.Floor(BytesRead/1024));

-- Check if the cancel button was pressed
if StatusDlg.IsCancelled() then
-- Cancel button was pressed. Hide status dialog and terminate download
StatusDlg.Hide();
return false;
else
-- Cancel button was not pressed, determine message to be displayed
if FileSize == 0 then
-- Display 'size unknown' message
StatusDlg.SetStatusText("Size Unknown (" .. Math.Floor(BytesRead/1024) .. "kb downloaded so far)");
elseif FileSize > 0 then
-- Display 'downloaded of total' message
StatusDlg.SetStatusText("Downloaded " .. Math.Floor(BytesRead/1024) .. " kb of " .. Math.Floor(FileSize/1024) .. " kb");
end

-- Determine if end of download was reached:
-- Message will = "", the end of the download is a 'busy' state
-- BytesRead will be > 0, because more than 1 byte will have been transferred
-- BytesRead will = FileSize, unless FileSize is unknown (0)
if (Message == "") and (BytesRead > 0) and (BytesRead == FileSize or FileSize == 0) then
-- The download has completed, hide the status dialog and display complete message
StatusDlg.Hide();
Dialog.Message("Download Complete", Math.Floor(BytesRead/1024) .. " kb have been downloaded");
return false;
else
-- The download has not ended, continue to download
return true;
end
end
end

-- Call the ShowStatusWindow() function
ShowStatusWindow();

-- Download the file using a callback function
HTTP.Download("http://www.yourdomain.com/download_folder/file.ext", "c:\\file.ext", MODE_BINARY, 20, 80, nil, nil, DownloadStatus);

Note: ShowStatusWindow() shows the status window and sets the title. DownloadStatus() is the custom callback function, and is called by HTTP.Download.


Package Properties

Overview

Package ID:

A string used to identify the current package. This ID is only used by the developer and will not be seen by the end user.

Display name:

The display name for the current package. This name is normally used for display purposes on screens and dialogs that the end user will see such as the Select Packages screen.

Description:

A description of the current package. This information can be used to further describe the contents of the package and can be displayed on screens or dialogs such as the Select Packages screen.

Additional disk space (KB):

The additional disk space you would like to add to this package. Setup Factory automatically calculates the disk space required for all files within each package. This setting can be used to add additional required space to this package's calculation for content that may not be directly part of the installation file, such as external downloads or modules.

Initial State

The following are the initial default values of the current package:

Install this package

Whether or not the files in the current package should be installed by default. If checked, all files within this package will be installed. If it is unchecked, they will not. The state of this setting can be detected at runtime using the SetupData.GetPackageProperties action, and modified using the SetupData.SetPackageProperties action.

Allow user to change

Whether or not the current package will be enabled at runtime. When a package is enabled, its install state can be modified by the user, such as on the Select Packages screen. If it is disabled, the package's state cannot be modified by the user. The state of this setting can be detected at runtime using the SetupData.GetPackageProperties action, and modified using the SetupData.SetPackageProperties action.

Language:

The supported language you want to translate the package text for. You can click the select button to select a different language currently supported in your setup.

Note: You can add additional language support on the Languages dialog which can be accessed by going to Project > Languages...


Columns Archive

Columns

Archive External

Columns:

A list of the available columns that can be shown in Setup Factory on the Archive tab. Each column's visibility is controlled by the state of its checkbox. All columns whose checkboxes are checked will be shown in the design window. This list also controls the order of the columns in the design window. The first item listed on this dialog is shown as the left-most column and the last item is the right-most column.

Check All

Mark all columns as checked so they are visible in the design window.

Uncheck All

Uncheck all columns, so there are no columns visible in the design window.

Up

Move the selected column up one position in the list. This means that the column will appear closer to the left side of the design window.

Down

Move the selected column down one position in the list. This means that the column will appear closer to the right side of the design window.

Defaults

Restore the visibility and ordering of the columns to their default state. This means they will appear as they did when you first opened Setup Factory.


Columns External

Columns

Archive External

Columns:

A list of the available columns that can be shown in Setup Factory on the External tab. Each column's visibility is controlled by the state of its checkbox. All columns whose checkboxes are checked will be shown in the design window. This list also controls the order of the columns in the design window. The first item listed on this dialog is shown as the left-most column and the last item is the right-most column.

Check All

Mark all columns as checked so they are visible in the design window.

Uncheck All

Uncheck all columns, so there are no columns visible in the design window.

Up

Move the selected column up one position in the list. This means that the column will appear closer to the left side of the design window.

Down

Move the selected column down one position in the list. This means that the column will appear closer to the right side of the design window.

Defaults

Restore the visibility and ordering of the columns to their default state. This means they will appear as they did when you first opened Setup Factory.


Start a New Project

Overview

This dialog appears by default whenever you start a new project (File > New) as well as when Setup Factory first starts up. It provides you with a quick way to start new projects as well as to open an existing project.

Create a new project

Create a new installer project.

Show project wizard

If checked, the project wizard will help you get your new project setup. If unchecked, a blank "default" project will be created without showing the project wizard. When you first start using Setup Factory it is a good idea to leave the project wizards on.

Open an existing project

If selected, you can re-open an existing Setup Factory project file. You can choose from a list of recently used project files or click the Browse button to browse your system to locate a file.

Note: When opening a project file created with a previous version, Setup Factory 9 will analyze your project and may create a report detailing where minor changes may need to be made for compatibility. See Changes to Setup Factory for more information.

Tip: You can select Setup Factory 6.0, 7.0, and 8.0 project files on the Open Project File dialog using the "Files of type" drop down.


Add Action Plugin

Overview

Available action plugins:

These are the available action plugins installed on your system that can be added to your project. You can select a plugin and click OK to add the it to your setup.

Note: As of Setup Factory 9, only plugins created with version 2.0 of the SDK (or higher) are supported.

Note: Any action plugins that are located in Includes\Plugins within the Setup Factory program directory, and that were created with version 2.0 (or higher) of the Plugin SDK, will be shown in the list.

Note: Ensure that the plugin you select matches the chosen setup platform.

Plugin information:

A summary of information about the highlighted plugin such as its name, author and copyright. This information may vary between authors.


Add Dependency Module

Overview

A list of the available dependency modules installed on your system that can be added to your current install.

You can select a module and click OK to add the module to your setup.

Note: Ensure that the dependency module you select is correct for the chosen setup platform.

Tip: There may be other dependency modules available for download. You can download more modules by clicking the More Modules button on the Dependencies tab of the Resources dialog.

Description

A description of the currently selected dependency module containing details about its functionality and requirements.


Global Script File Properties

Overview

Filename:

The full path and filename of the script file on your development system you want to include in your project. You can click the Browse button to select a script file (*.lua).

Tip: There are a variety of Indigo Rose created script files that are shipped with Setup Factory. All available script files can be found in the Scripts folder, normally located in C:\Program Files\Setup Factory 9\Includes\Scripts. An example of a file that can be found there is Detect_Acrobat.lua.

Build configurations:

The build configurations you want the specified script file to be a part of. You can check or uncheck the boxes in the build configurations tree to include or exclude it.


Plugin Build Configurations

Overview

Build configurations:

The build configurations you want the specified action plugin to be a part of. You can check or uncheck the boxes in the build configurations tree to include or exclude it.


Primer File Properties

Overview

Filename:

The full path and filename of the file you want to include as a primer file. You can click the Browse button to select a file from your development system.

Delete when setup exits:

Delete this primer file from the user's system if the setup exits in any way.

Used by uninstall

Make this file available during the uninstall. This file will be copied to the Uninstall files folder during the installation.

Build configurations:

The build configurations that will include the current primer file. You can check or uncheck the boxes in the build configurations tree.


Build

Dependency Module Properties

Information Detection Installation Files Build

Build configurations:

The build configurations you want the specified dependency module to be a part of. You can check or uncheck the boxes in the build configurations tree to include or exclude it.


Detection

Dependency Module Properties

Information Detection Installation Files Build

Detection function name:

The name of the function in the dependency detection script that Setup Factory will call in order to determine whether or not the technology is present on the user's system.

Dependency detection script:

An action editor window containing the action script that will be run to determine if the technology needs to be installed. This detection script must contain a function matching the name defined in the Detection function name field. If the detection function returns the value false, this means that the technology wasn't found on the user's system and should be installed by running the action script on the Installation tab. If the function returns the value true, this means that the technology already exists and doesn't need to be installed.


Files

Dependency Module Properties

Information Detection Installation Files Build

Unique run-time folder name:

A unique name that will be used for the folder containing the extracted dependency files for the current module. This folder will be created in the path stored in the variable _TempLaunchFolder.

Dependency files:

A list of the dependency files that are necessary to install the current technology. Files can be added by clicking the New button, and either entering the source path directly, or clicking the browse button (...) to select a file from your system. Files in the list can also be removed, or moved up and down in the list using the Delete, Move Up and Move Down buttons.

All files listed will automatically be built into the setup and only extracted if the detection script determines it is needed. These files are extracted to the folder specified in the Unique run-time folder name field.

Note: Deleting a file from the dependency file list only removes its reference and does not modify the file on your system.


Information

Dependency Module Properties

Information Detection Installation Files Build

Name:

The design-time name of the current dependency module.

Description:

A brief description of the module including links to additional information.

Note: This information is for developer use and is only available at design time. The end user will not see this information.


Installation

Dependency Module Properties

Information Detection Installation Files Build

Dependency installation script:

An action editor window containing the action script that will be run if the dependency detection script determined that the technology wasn't found on the user's system (false was returned by the detection function).


Progress Screen Attributes

Overview

Screen

Screen ID:

The name that is used to identify the screen at design time in the screens list.

Window title:

The text that will be displayed in the Windows title bar for this specific screen.

Banner

The type of banner to use:

Top

Display a banner across the top of the screen.

Side

Display a side banner on the left hand side of the screen.

None

Don't display any banner on the screen.

Heading text:

The heading text you want to appear in the banner.

Subheading text:

The subheading text you want to appear in the banner.

Buttons

Note: Using the ampersand character (&) in a button's text will make the character to its right a mnemonic key for the control.

Cancel:

The text you want to display on the Cancel button. The Cancel button will fire the screen's On Cancel event.

Enabled

Enable the button so it responds to user interaction. When a button is disabled, it will not respond to any mouse overs or clicks and will not perform any actions until it is enabled.

Note: You can use the DlgButton.SetProperties to enable a button.

Visible

Set the button's initial visibility (whether it's visible when the screen is displayed).

Note: You can use the DlgButton.SetProperties action to make the button visible or invisible at run time.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.


Screen Attributes

Overview

Screen

Screen ID:

The name that is used to identify the screen at design time in the screens list.

Note: The Screen ID has a maximum length of 255 characters.

Window title:

The text that will be displayed in the Windows title bar for this specific screen.

Banner

The type of banner to use for the current screen:

Top

Display a banner across the top of the screen.

Side

Display a side banner on the left hand side of the screen.

None

Don't display any banner on the screen.

Heading text:

The heading text you want to appear in the banner.

Subheading text:

The subheading text you want to appear in the banner.

Buttons

Note: Using the ampersand character (&) in a button's text will make the character to its right a mnemonic key for the control.

Next:

The text you want to display on the Next button. The Next button will fire the screen's On Next event.

Enabled

Enable the button so it responds to user interaction. When a button is disabled, it will not respond to any mouse overs or clicks and will not perform any actions until it is enabled.

Note: You can use the DlgButton.SetProperties to enable a button.

Visible

Set the button's initial visibility (whether it's visible when the screen is displayed).

Note: You can use the DlgButton.SetProperties action to make the button visible or invisible at run time.

Back:

The text you want to display on the Back button. The Back button will fire the screen's On Back event.

Enabled

Enable the button so it responds to user interaction. When a button is disabled, it will not respond to any mouse overs or clicks and will not perform any actions until it is enabled.

Note: You can use the DlgButton.SetProperties to enable a button.

Visible

Set the button's initial visibility (whether it's visible when the screen is displayed).

Note: You can use the DlgButton.SetProperties action to make the button visible or invisible at run time.

Cancel:

The text you want to display on the Cancel button. The Cancel button will fire the screen's On Cancel event.

Enabled

Enable the button so it responds to user interaction. When a button is disabled, it will not respond to any mouse overs or clicks and will not perform any actions until it is enabled.

Note: You can use the DlgButton.SetProperties to enable a button.

Visible

Set the button's initial visibility (whether it's visible when the screen is displayed).

Note: You can use the DlgButton.SetProperties action to make the button visible or invisible at run time.

Help:

The text you want to display on the Help button. The Help button will fire the screen's On Help event.

Enabled

Enable the button so it responds to user interaction. When a button is disabled, it will not respond to any mouse overs or clicks and will not perform any actions until it is enabled.

Note: You can use the DlgButton.SetProperties to enable a button.

Visible

Set the button's initial visibility (whether it's visible when the screen is displayed).

Note: You can use the DlgButton.SetProperties action to make the button visible or invisible at run time.

Language

Language:

The supported language you want to translate the screen text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...

Tip: You can see how the screen will look at runtime by clicking the Preview button.


Button Properties

Overview

Button text:

The text you want to appear on the button.

Note: Using the ampersand character (&) in a button's text will make the character to its right a mnemonic key for the control.

Description text:

The text you want to appear to the right of the button.

Note: Using the ampersand character (&) in a button's description text will make the character to its right a mnemonic key for the control.

Defaults

Visible

Set the initial visibility of the button (whether it's visible when the screen is displayed).

Enabled

Enable the button so it responds to user interaction. When a button is disabled, it will appear greyed out and cannot be clicked.

Language

Language:

The supported language you want to translate the button for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Check Box Properties

Overview

Text

Label:

The text you want to display to the right of the check box.

Note: Using the ampersand character (&) in a label's text will make the character to its right a mnemonic key for the control.

States

Enabled

Enable the check box so it responds to user interaction. When an check box is disabled, it will appear greyed out and cannot be edited.

Visible

Set the initial visibility of the check box (whether it's visible when the screen is displayed).

Default Value

Unchecked

Show the check box as unchecked when the screen displays.

Checked

Show the check box as checked when the screen displays.

Result Variable

Store state in LUA variable:

The LUA variable that you want to store the state of the check box. If the check box is checked when leaving this screen, true will be stored. If the check box is unchecked, false is stored.

Language

Language:

The supported language you want to translate the check box for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Combo Box Properties

Overview

Combo Box

Label:

The text you want to display above the combo box field.

Note: Using the ampersand character (&) in a label's text will make the character to its right a mnemonic key for the control.

Default text:

The initial text you want to display inside the combo box field.

Items:

The list of items you want to appear in the combo box. Each line in the items list represents one combo box item.

Sorted

Sort the combo box items alphabetically at runtime. If this option is unchecked, combo box items will be displayed in the order they appear at design time or added at runtime.

Style:

The combo box style you want to use. Choose from:

Drop-down list

Make the combo box selection read-only. (The selected text cannot be edited.)

Drop-down edit

Make the combo box selection editable. (The selected text can be edited.)

Store selection in variable:

The custom session variable you want to use to store the current text in the combo box field.

Note: If you plan to include more than one Combo Boxes screen in your setup, you must ensure each variable name is unique.

Lines to show in drop down:

The number of lines you want to show in the combo box drop down.

Enabled

Enable the combo box so it responds to user interaction. When a combo box is disabled, it will appear greyed out and no selection can be made.

Visible

Set the initial visibility of the combo box (whether it's visible when the screen is displayed).

Language

Language:

The supported language you want to translate the combo box for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Billboard Properties

Overview

Image Files

The image files you wish to show in the billboard control. These images will automatically be included in your setup.

Click the add button to choose an image file through the Select Image File dialog. Repeat this step if you wish to include multiple files, or click the add folder button to add all supported images within a folder on your system. You can manipulate the image files list by first highlighting the image file, then either clicking the edit, delete, or the arrow buttons to achieve the desired image list.

Note: The following image formats are supported in the billboard control: JPG, BMP, TIFF, GIF, PNG, PCX, and TGA. If you require alpha transparency, use 32-bit .PNG format.

Background Style

Solid

The background color for the control. You can click the select button to bring up a color chooser.

Transparent

Make the background of the control transparent.

Border Style

Solid

The border color for the control. You can click the select button to bring up a color chooser.

None

Don't show any border for the control.

Timer

Interval (milliseconds):

The duration to show each image in the control (in milliseconds).

Auto-start

Start playing the billboard automatically (as soon as the screen is shown).

Note: If this option is unchecked, the billboard will not play until you start it with a DlgBillboard.Play action.

Options

Resize mode:

The resize mode to use for the images. Choose from:

Crop

Fill the area defined by the control's bounding box and crop any parts that extends beyond the control's dimensions.

Proportional

Resize the image so it fits inside the area defined by the control's bounding box using the image's largest dimension.

Stretch

Resize the image to fill the entire area defined by the control's bounding box.

Note: This setting ignores the image's original dimensions. The image may appear distorted as a result.

Loop

Automatically begin playing from the beginning again whenever the billboard reaches the end.

Note: If this option is checked, the On Finish event on the Custom Progress screen will not be fired.

Shuffle

Play the images in the control's image file list in random order. If unchecked, they will be played in the order they were defined at design-time.

Transitions

Show a transition effect between images.

No enlarge

If checked, and Resize mode is set to "Proportional," any images that are smaller than the control's dimensions will be centered in the control, and not enlarged to fit the dimensions of the control. If unchecked, images will be proportionally resized to fit the control's dimensions.


Button Properties

Overview

Button text:

The text you want to appear on the button.

Note: Using the ampersand character (&) in a button's text will make the character to its right a mnemonic key for the control.

Defaults

Visible

Set the initial visibility of the button (whether it's visible when the screen is displayed).

Enabled

Enable the button so it responds to user interaction. When a button is disabled, it will appear greyed out and cannot be clicked.

Language

Language:

The supported language you want to translate the button for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Check Box Properties

Overview

Text

Label:

The text you want to display to the right of the check box.

Note: Using the ampersand character (&) in a label's text will make the character to its right a mnemonic key for the control.

States

Enabled

Enable the check box so it responds to user interaction. When a check box is disabled, it will appear greyed out and cannot be edited.

Visible

Set the initial visibility of the check box (whether it's visible when the screen is displayed).

Default Value

Unchecked

Show the check box as unchecked when the screen displays.

Checked

Show the check box as checked when the screen displays.

Result Variable

Store state in Lua variable:

The LUA variable that you want to store the state of the check box. If the check box is checked when leaving this screen, true will be stored. If the check box is unchecked, false is stored.

Language

Language:

The supported language you want to translate the check box for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Combo Box Properties

Overview

Combo Box

Default text:

The initial text you want to display inside the combo box field.

Items:

The list of items you want to appear in the combo box. Each line in the items list represents one combo box item.

Sorted

Sort the combo box items alphabetically at runtime. If this option is unchecked, combo box items will be displayed in the order they appear at design time or added at runtime.

Style:

The combo box style you want to use. Choose from:

Drop-down list

Make the combo box selection read-only. (The selected text cannot be edited.)

Drop-down edit

Make the combo box selection editable. (The selected text can be edited.)

Store selection in variable:

The custom session variable you want to use to store the current text in the combo box field.

Lines to show in drop down:

The number of lines you want to show in the combo box drop down.

Enabled

Enable the combo box so it responds to user interaction. When an combo box is disabled, it will appear greyed out and no selection can be made.

Visible

Set the initial visibility of the combo box (whether it's visible when the screen is displayed).

Language

Language:

The supported language you want to translate the combo box for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Edit Properties

Overview

Settings

Default text:

The initial text you want to display inside the edit field.

Store in session variable:

The custom session variable you want to use to store the text in the edit field.

Note: If you plan to include more than one Edit Field control, you must ensure each variable name is unique.

Input Style

The style of the edit field you want to use. Choose from:

Standard

Display the input text normally.

Password

Hide any text that the user types by displaying asterisks (****).

Input mask

Use an input mask to control input into the edit field.

Mask:

The input mask you want to use to control the data the user inputs into the object. Input masks let you pre-format the user's response a bit with "guide" characters, and help prevent errors by performing keystroke validation.

One common input mask is a telephone number. It would appear as (###) ###-####.
The "#" character in the input mask is a special digit placeholder (0-9). For every # in the input mask, the user will only be able to enter a digit between 0 and 9. At runtime, the user will only be able to enter 10 numeric characters and will appear as a formatted telephone number such as (204) 946-0263.

You can also include alphabetic characters in an input mask. For example a Canadian postal code can be represented as ?#? #?#. The "?" character in the input mask is a special alphabetic placeholder (a-Z). For every ? in the input mask, the user will only be able to enter a letter from a to z. For example, R3B 0R3 is one valid postal code that the user could enter. The mask would prevent the user from entering two sequential alphabetic characters or numbers.

Placeholder:

Text used as a placeholder for the input mask. This can be used as sample input until the user fills the input mask. For the telephone number input mask mentioned in the above example, you could include a sample digit as the placeholder such as 9. At runtime it would appear as (999) 999-9999 until the user replaced these digits with their own.

States

Enabled

Enable the edit field so it responds to user interaction. When an edit field is disabled, it will appear greyed out and cannot be edited.

Visible

Set the initial visibility of the edit field (whether it's visible when the screen is displayed).

Multiline

Enable multiple lines of input text in the edit field control. If this option is disabled, the input box will be limited to one line of text.

Alignment

Left

Left-align the text within the edit field, like so:

This text is left-aligned

Center

Center the text within the edit field, like so:

This text is centered

Right

Right-align the text within the edit field, like so:

This text is right-aligned

Language

Language:

The supported language you want to translate the edit field for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Group Box Properties

Overview

Button text:

The text you want to appear on the group box.

Note: Using the ampersand character (&) in the text will make the character to its right a mnemonic key for the control.

Defaults

Visible

Set the initial visibility of the control (whether it's visible when the screen is displayed).

Enabled

Enable the control so it responds to user interaction. When a control is disabled, it will appear greyed out and cannot be clicked.

Language

Language:

The supported language you want to translate the group box for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


List Box Properties

Overview

List Box

Items:

The items you want to show in the list box. Each line in this area will be shown as one list box item.

Options

Enabled

Enable the list box so it responds to user interaction. When a list box is disabled, all of its items will appear greyed out and cannot be selected.

Visible

Set the initial visibility of the list box (whether it's visible when the screen is displayed).

Sorted

Sort the list box items alphabetically at run time. If this option is unchecked, list box items will be displayed in the order they appear at design time or added at run time.

Multi select

Enable multiple list box items to be selected at one time.

Style

List Box

Use a standard list box style.

Checklist Box

Use a checklist box style. A checklist box is a standard list box combined with a check box for each item.

Language

Language:

The supported language you want to translate the list box for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Progress Bar Properties

Overview

Note: If the screen's theme does not use custom colors, the progress bar has XP style turned on, and the operating system is Windows XP or newer (it uses themes) then Setup Factory will use the current Windows theme when drawing the progress bar. This means that the progress bar will ignore the Segmented or Smooth settings below and will be smooth or segmented depending on the available Windows Theme.

Text:

The text you want to appear on the progress bar.

Segmented

Use segmented bars to represent progress.

Smooth

Use a solid bar to represent progress.

XP style

Use an XP style progress meter.

Defaults

Visible

Set the initial visibility of the control (whether it's visible when the screen is displayed).

Enabled

Enable the control so it responds to user interaction. When a control is disabled, it will appear greyed out and cannot be clicked.

Language

Language:

The supported language you want to translate the progress bar for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Radio Button Properties

Overview

Button text:

The text you want to display to the right of the radio button.

Note: Using the ampersand character (&) in a radio button's text will make the character to its right a mnemonic key for the control.

Defaults

Visible

Set the initial visibility of the radio button (whether it's visible when the screen is displayed).

Enabled

Enable the radio button so it responds to user interaction. When an radio button is disabled, it will appear greyed out and cannot be edited.

Language

Language:

The supported language you want to translate the radio button for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Scrollable Text Properties

Overview

Text Type

Plain text

Display the text in plain ASCII format.

Note: If you are loading a file that is not local, you must use the HTML text type instead.

HTML

Display the text in HTML format.

Screen Text

Load from file

Load the text from a file at runtime. You can click the Browse button to select a file from your system. This file will automatically be included as a resource in your install.

Note: If you are referencing an external file that is not local using a session variable or hard-coded path, you must use the HTML text type.

Note: Each language contains its own "Load from file" value. This means you can load a different file to be displayed in the control for each language configured in your project.

Specify now

Specify the screen text now either by directly typing it in, pasting the text, or importing it from a file.

Import

Select a file from your system that you want to import immediately.

Defaults

Visible

Set the initial visibility of the control (whether it's visible when the screen is displayed).

Enabled

Enable the control so it responds to user interaction. When a control is disabled, it will appear greyed out and cannot be clicked.

Language

Language:

The supported language you want to translate the scrollable text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Select Package Tree Properties

Overview

Select Packages

Tree:

A tree structure consisting of categories and packages. A category is a selectable group of packages that when chosen, selects all of the contents within it. Categories can contain packages as well as other categories.

Add

Open the Category Properties dialog where you can create a new package category.

Remove

Remove the selected category or package from the package tree.

Edit

Open the Category Properties dialog if a category is currently selected, or the Package Properties dialog if a package is currently selected, where you can edit their properties.

Up

Move the selected category or package up one position in the package tree.

Down

Move the selected category or package down one position in the package tree.

Right

Move the selected category or package right one position in the package tree. This means that the selected item will be moved down one position in the tree structure.

Left

Move the selected category or package left one position in the package tree. This means that the selected item will be moved up one position in the tree structure.

Packages:

A list of all the current packages defined in the setup, defined by their package IDs.

Add package ( )

Add the selected package to the package tree.

Remove package ( )

Remove the selected package from the package tree.

Show all

Show all available packages defined in the setup.

Show unused

Only show unused packages in the list.

Language

Language:

The supported language you want to translate the text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Text Properties

Overview

Text:

The text you want to appear on the control.

Note: Using the ampersand character (&) in the control's text will make the character to its right a mnemonic key for the control.

Defaults

Visible

Set the initial visibility of the control (whether it's visible when the screen is displayed).

Use body heading font

Controls the font of the text control. If checked the theme's "Body Heading" font will be used for the control. If not checked then the theme's "Body Text" font will be used.

Language

Language:

The supported language you want to translate the text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Edit Field Properties

Overview

Text

Label:

The text you want to display above the edit field.

Note: Using the ampersand character (&) in a label's text will make the character to its right a mnemonic key for the control.

Default text:

The initial text you want to display inside the edit field.

Button

Show button

Show a button on the right hand side of the edit field. For example, you could use this button to open a file browse or folder browse dialog when the user clicks the button.

Text:

The text you want to display on the button.

Note: Using the ampersand character (&) in a button's text will make the character to its right a mnemonic key for the control.

Session Variable

Store in:

The custom session variable you want to use to store the text in the edit field.

Note: If you plan to include more than one Edit Fields screen in your setup, you must ensure each variable name is unique.

Input Style

The style of the edit field you want to use. Choose from:

Standard

Display the input text normally.

Password

Hide any text that the user types by displaying asterisks (****).

Input mask

Use an input mask to control input into the edit field.

Mask:

The input mask you want to use to control the data the user inputs into the object. Input masks let you pre-format the user's response a bit with "guide" characters, and help prevent errors by performing keystroke validation.

One common input mask is a telephone number. It would appear as (###) ###-####.
The "#" character in the input mask is a special digit placeholder (0-9). For every # in the input mask, the user will only be able to enter a digit between 0 and 9. At runtime, the user will only be able to enter 10 numeric characters and will appear as a formatted telephone number such as (204) 946-0263.

You can also include alphabetic characters in an input mask. For example a Canadian postal code can be represented as ?#? #?#. The "?" character in the input mask is a special alphabetic placeholder (a-Z). For every ? in the input mask, the user will only be able to enter a letter from a to z. For example, R3B 0R3 is one valid postal code that the user could enter. The mask would prevent the user from entering two sequential alphabetic characters or numbers.

Placeholder:

Text used as a placeholder for the input mask. This can be used as sample input until the user fills the input mask. For the telephone number input mask mentioned in the above example, you could include a sample digit as the placeholder such as 9. At runtime it would appear as (999) 999-9999 until the user replaced these digits with their own.

Alignment

Left

Left-align the text within the edit field, like so:

This text is left-aligned

Center

Center the text within the edit field, like so:

This text is centered

Right

Right-align the text within the edit field, like so:

This text is right-aligned

Layout

Start new row

Start a new row for this edit field. If unchecked, this edit field will be placed to the right of the previously created edit field. If there is no room for it to be inserted on the current row, a new row will be started. The maximum number of possible rows is 8 (with no banner or heading/label text) and 4 (with a banner and heading/label text).

Width (in columns):

The width (in columns) you want for this edit field. The maximum width for an edit field is 4 and the minimum is 1. This means you can include a maximum of 4 edit fields on each row, or one that fills the entire row.

States

Enabled

Enable the edit field so it responds to user interaction. When an edit field is disabled, it will appear greyed out and cannot be edited.

Visible

Set the initial visibility of the edit field (whether it's visible when the screen is displayed).

Language

Language:

The supported language you want to translate the edit field for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Radio Button Properties

Overview

Text

Label:

The text you want to display to the right of the radio button.

Note: Using the ampersand character (&) in the label text will make the character to its right a mnemonic key for the control.

States

Enabled

Enable the radio button so it responds to user interaction. When an radio button is disabled, it will appear greyed out and cannot be edited.

Visible

Set the initial visibility of the radio button (whether it's visible when the screen is displayed).

Language

Language:

The supported language you want to translate the radio button for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Category Properties

Overview

Display name:

The name to display on the package category.

Description:

The description text of the current category. This text will display in the area to the right of the package tree when this category is selected.

Defaults

Install

Initially select this category's contents to be installed when shown. If unchecked, the category checkbox will initially be unchecked.

Enabled

Enable the category so it responds to user interaction. When an category is disabled, it will appear greyed out and cannot be edited by the user.

Expanded

Automatically expand this category to display its contents when the screen is displayed. If unchecked, this category will be in its collapsed state.

Language

Language:

The supported language you want to translate the category text for. You can click the select button ( [image] ) to select a different language currently supported in your setup.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Add to Gallery

Overview

Note: Created screens will be saved in a "Screens" folder located in the all user profile of Application Data. For example: C:\Documents and Settings\All Users\Application Data\IndigoRose\Setup Factory\9.0\Screens

Screen name:

The name of the screen you want to add to the screen gallery. This is the name that will appear in the list of available screens.

Description:

A brief description of the screen you want to add. This description will be shown if it is selected in the Screen Gallery.

Gallery Visibility

The screens available in the Screen Gallery depend upon what point in the install they are being added.

Before Installing

Whether or not this screen should be available as a Before Installing screen in the Screen Gallery.

Before Uninstalling

Whether or not this screen should be available as a Before Uninstalling screen in the Screen Gallery.

While Installing

Whether or not this screen should be available as a While Installing screen in the Screen Gallery.

While Uninstalling

Whether or not this screen should be available as a While Uninstalling screen in the Screen Gallery.

After Installing

Whether or not this screen should be available as an After Installing screen in the Screen Gallery.

After Uninstalling

Whether or not this screen should be available as an After Uninstalling screen in the Screen Gallery.


Screen Gallery

Overview

Screens:

A list of all of the available screens that can be added at this stage of the install. If you select a screen, an image preview will be shown in the Preview area of the dialog.

Tip: You can double click on the screen to add it to your project, or click the OK button.

Description:

A brief description of the currently selected screen.

Preview:

An image preview of the selected screen.


Theme Properties

Style

Colors

Use Custom Colors

Customize the colors used in the current project theme. This includes properties such as its text and background. Select True to customize these settings. You can click the select button ( [image] ) to bring up a color chooser.

Top Banner BG

The background color to use for the top banner.

Top Banner Text

The color to use for the text within the top banner.

Body BG

The background color to use for the screen body.

Body Text

The color to use for the body text.

Footer BG

The background color to use for the footer.

Controls BG

The background color to use for the screen controls.

Controls Text

The color to use for control text.

Controls 3D Face

The face color to use for controls that have a three dimensional appearance such as buttons.

Button Text

The color of button text.

3D Highlight

The color to use to highlight any three dimensional screen property.

3D Light

The light color to use on any three dimensional screen property. This color is normally present beside the highlight color.

3D Shadow

The color to use as the shadow on any three dimensional screen property.

3D Dark Shadow

The color to use as the dark shadow on any three dimensional screen property. This shadow color is normally present beside the shadow.

Controls Disabled Text

The color to use for control text that is disabled.

Progress Bar

The color to use for progress bars.

Fonts

Use Custom Fonts

Customize the fonts used for text in the current project theme. Select True to customize these settings. You can click the edit button ( [image] ) to open the Font dialog where you can edit all of the font settings for the selected text item.

Note: Each screen contains only one set of font settings. If you're using custom fonts and including multiple languages, ensure that your chosen font contains the required character set for your languages. If you need to override a font's character set (script) in the setup on a global basis, you may use the built-in global variable _UseSystemCharacterSet to use the system's default character set instead.

Top Banner Heading

The font setting to use for heading text in a top banner.

Top Banner Subheading

The font setting to use for the subheading text in a top banner.

Body Heading

The font setting to use for the body heading text.

Body Text

The font setting to use for the body text.

Controls

The font setting to use for any screen control text.

Images

Top Banner

The full path to the image you want to display if the screen contains a top banner. You can click the edit ( [image] ) button to select an image file. The following image formats are supported in Setup Factory:

*.bmp; *.jpg; *.pcx; *.png; *.tga; *.tif;

Note: For optimal performance, 24 bit images should be used.

Side Banner

The full path to the image you want to display if the screen contains a side banner. You can click the edit ( [image] ) button to select an image file.

Note: For optimal performance, 24 bit images should be used.

Body

The full path to the image you want to display in the body of the screen. This means that this image will cover the entire background of the screen and if any banners are applied, they will be drawn over top of the body image. You can click the edit ( [image] ) button to select an image file.

Note: For optimal performance, 24 bit images should be used.

Fill Footer

Extend the body image so that it covers the footer area. The footer area is located at the bottom of each screen and usually contains buttons such as the Back, Next and Cancel buttons. Select True to fill the footer area.

Separators

Header

Show a header separator if the screen contains a top banner. The header separator is a line that separates the top banner from the body of the screen. Select True to show a header separator.

Footer

Show a footer separator on all screens. The footer separator is a line that separates the body of the screen from the footer area, which contains the standard buttons. Select True to show a footer separator.

Offsets

The control area offsets control the placement of the controls and text in the body of the screen. Each banner style can contain different control area offsets.

Top Banner

The control area offsets for screens that contain a top banner.

Left:

The distance in pixels from the left hand side of the screen that the control area should start.

Top:

The distance in pixels from the edge of the top banner image that the control area should start.

Right:

The distance in pixels from the right hand side of the screen that the control area should end.

Bottom:

The distance in pixels from the bottom of the screen body (above the footer) that the control area should end.

Side Banner

The control area offsets for screens that contain a side banner.

Left:

The distance in pixels from the edge of the side banner image that the control area should start.

Top:

The distance in pixels from the top of the screen that the control area should start.

Right:

The distance in pixels from the right hand side of the screen that the control area should end.

Bottom:

The distance in pixels from the bottom of the screen body (above the footer) that the control area should end.

No Banner

Configure the control area offsets for screens that contain no banner.

Left:

The distance in pixels from the left hand side of the screen that the control area should start.

Top:

The distance in pixels from the top of the screen that the control area should start.

Right:

The distance in pixels from the right hand side of the screen that the control area should end.

Bottom:

The distance in pixels from the bottom of the screen body (above the footer) that the control area should end.

Banner Text X

The distance in pixels from the left hand side of the screen that the heading text on the top banner should start. This setting only applies if a Top Banner is used.

Banner Text Y

The distance in pixels from the top of the screen that the heading text on the top banner should start. This setting only applies if a Top Banner is used.

Size

The width and height dimensions of the screen in pixels.

Screen Width

The width of the screen in pixels.

Screen Height

The height of the screen in pixels.

Preview:

An image preview of an example screen given the current theme properties. This theme will be applied to all screens in your project unless it is overridden on a per screen basis using the Override project theme option on the Style tab of each screen's properties.

Preview banner style:

The banner style you want to use in the screen preview.

Top

Show a top banner when previewing a screen.

Side

Show a side banner when previewing a screen.

None

Don't show any banner when previewing a screen.


Generate Serial Number

Overview

The Generate Serial Number dialog allows you to generate a list of serial numbers to include in your setup.

Number of serial numbers to generate:

The number of serial numbers to generate. The maximum number of serial numbers you can generate is 2,000,000,000 (2 billion).

Generate sequential serial numbers

Generate sequential serial numbers starting with the one specified in the First serial number field.

First serial number:

The first serial number in the sequence. The following rules apply to the first serial number:

  • Must consist only of alphanumeric characters and dashes ("A-Z", "a-z", "0-9", "-").

  • Cannot contain spaces.

  • Cannot start or end with a dash.

Generate random serial numbers

Generate random serial numbers based on the mask entered in the Serial number mask field.

Serial number mask:

A mask of the serial numbers to generate. You can click the drop-down to select a predefined mask, or create your own with a combination of mask characters.

The following mask characters may be used:

Character | What will be generated
# | Random number
* | Uppercase letter ("A-Z")
@ | Lowercase letter ("a-z")
? | Random number or uppercase letter ("A-Z", "0-9")
- | A dash character
A literal character | The literal character will be displayed

The following predefined masks are available:

Mask | Example of what could be generated
####-####-####-#### | 4754-8345-1970-4486
PW##-#### | PW18-2106
?????-????? | MCMEU-0JSTC
#@#@#@#@ | 3y0b9y7v
****-CD-#### | AGPN-CD-7101
CDKEY-????-####-**** | CDKEY-LRAC-1333-IDST
*###-***-###* | J363-DCU-621I


Serial Number List Properties

Overview

The Serial Number List Properties dialog allows you to edit the selected serial number list's properties.

List name:

The name of the serial number list.

Build configurations:

The build configurations the current list applies to.

Serial numbers in list:

The serial numbers in the current list.

Commands

Undo

Undoes the last serial number command performed.

Redo

Redoes the last serial number command undone.

Generate

Opens the Generate Serial Number dialog where you can automatically generate your serial number list. You can also access this menu item using Ctrl+G.

Find

Search through the serial number list for specific text. You can also access this menu item using Ctrl+F.

Sort

Sort the serial number list. Choose from:

Ascending

Sorts the serial number list in ascending order. You can also access this menu item using Ctrl+Up.

Descending

Sorts the serial number list in descending order. You can also access this menu item using Ctrl+Down.

Cut

Remove the currently selected text and store it in the Windows clipboard. Once on the clipboard, the text can be pasted to another location. You can also access this menu item using Ctrl+X.

Copy

Copy the currently selected text to the Windows clipboard. Once on the clipboard, the text can be pasted to another location. You can also access this menu item using Ctrl+C.

Paste

Paste the contents of the Windows clipboard to the currently selected serial number field. You can also access this menu item using Ctrl+V.

Select All

Select all of the serial numbers in the list. You can also access this menu item using Ctrl+A.

Clear All Serials

Remove all serial numbers from the serial number list. You can also access this menu item using Ctrl+K.

Delete Selected Rows

Remove the selected serial number(s) from the serial number list. You can also access this menu item using Ctrl+Delete.

Insert Row

Insert a row above the currently selected serial number. You can also access this menu item using Insert.

Insert Rows

Insert a specified number of rows above the currently selected serial number. You can also access this menu item using Ctrl+Insert.

Print

Print the serial number list. You can also access this menu item using Ctrl+P.

Import

Imports a text file into the serial number list. Imported text files should contain one serial number per line. You can also access this menu item using Ctrl+O. Serial number text files must be less than 2GB in size.

Export

Exports the current serial number list to a text file. The exported text file will contain one serial number per line. You can also access this menu item using Ctrl+S.


Uninstall Data File

Overview Settings Control Panel Shortcut Logs

The uninstall data file is an encrypted binary file containing everything configured at design time. This file is where all of the screen information is stored, as well as scripts and actions, and any settings configured.

The Uninstall Data File cannot be modified outside of the design environment.