Introduction

Contents

Welcome to Visual Patch!

Please select one of the following subjects:

What is Visual Patch?

Key Features of Visual Patch

What's New in Visual Patch

Frequently Asked Questions

The Visual Patch Interface

Importing Visual Patch 1.0 Projects

Patching On Windows Vista or Later

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

User's Guide

Scripting Guide

Action Reference

Variables

File Menu Commands

Edit Menu Commands

Versions Menu Commands

Project Menu Commands

Publish Menu Commands

View Menu Commands

Tools Menu Commands

Help Menu Commands

Miscellaneous topics

Ordering Information

Tip: A printable (PDF) version of the user's guide can be accessed from the Start menu. A printed and perfect-bound version of the user's guide is also available and can be ordered directly from www.ondemandmanuals.com.


Introduction

Contents What is Visual Patch?

Introduction

Visual Patch is a fast and efficient system for creating software patches. This unique solution features state-of-the-art binary differencing and compression algorithms, combined with a powerful full-history patching engine. Visual Patch makes an excellent addition to the toolbox of any software developer or IT manager.

In Visual Patch, we've improved the development environment to streamline your workflow and have introduced unprecedented flexibility with a brand-new scripting engine and action library. We've also added a customizable screen manager, project themes (skins), action plugins, MD5 security, and many other powerful and timesaving features.

You'll find that Visual Patch simplifies software version management. It turns the otherwise complicated task of managing point-releases into a fast and automated process. There is no easier way to make professional-quality, full-history binary patches for your software and other electronic content.

What is Visual Patch?

It doesn't matter what kind of electronic content you're distributing. Whether it's application software, databases, spreadsheets, video, audio or any other data, the likelihood is that it will change over time. That's why you need Visual Patch.

Visual Patch makes it easy to create professional, rock-solid software patches. As you release new software (documents, data, etc.), simply drag-and-drop the files into Visual Patch and it will automatically track and package the differences for you.

Using a sophisticated combination of binary differencing, data compression and MD5 fingerprinting, Visual Patch is able to create compact full-history software patches that outperform any comparable tool on a value and feature-by-feature basis.

Visual Patch is an integral part of a complete and effective approach to software lifecycle management. Software developers, network administrators and IT departments all require a professional tool for building software patches. As such, Visual Patch integrates seamlessly with other Indigo Rose products like Setup Factory 7.0 (software installation) and TrueUpdate (automated updating/patch delivery) to provide a complete solution for all aspects of software delivery.


Key Features of Visual Patch

Introduction

Contents Key Features of Visual Patch

Visual Dialog Editor

One of your most asked for features is finally here. You now 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.

Vista / Windows 7 / Windows 8 / Windows 8.1 / Windows 10 Compatible

Visual Patch's design workspace and generated patches are compatible with Windows Vista, Windows 7, Windows 8, Windows 8.1 and Windows 10 including a configurable "requested execution level" setting for the patch's manifest.

Custom Resource Stamping

Visual Patch allows you to use your own product icon and provides full control of the version information that you want written into the patch's resources.

Integrated Code Signing

Protect the integrity of your company and products by code signing your patches with your own certificate during the build process.

Sophisticated Version Management

Visual Patch makes it easy to manage your software releases. You can quickly and easily add, remove and organize product versions, and see all of the important details about your files. The toolbars, columns, sort-order, color-coding and other interface elements are fully customizable, allowing you to view only the information that is important to your workflow.

State-of-the-Art Binary Differencing Engine

Visual Patch features state-of-the-art binary differencing and compressions algorithms. This ensures you smaller and better performing software patches. The algorithms used by Visual Patch were developed specifically for their impressive speed characteristics. Whereas software patching was once a notoriously slow and cumbersome process, companies choosing Visual Patch have a distinct advantage.

Full-History Patching

With Visual Patch, you have full control over which versions of your software can be patched with a single executable. While some vendors will choose to include only a single version update, others may offer a patch that can update any version that has ever been released. Visual Patch can handle either extreme, or anything in between. Unlike some other products, Visual Patch's full-history patching ability can update any version of your software to the latest release. With only have one file to download, Visual Patch brand patches are much more user friendly. Your users won't have to worry about finding multiple patches and applying them in the correct order as they would if you used other, less sophisticated patch builders.

Internet Ready, Single-File Executable

Smaller and faster means a better experience for your customers, and Visual Patch delivers. Compare our tiny ~500 KB runtime overhead to the competition and see for yourself. Patches created with Visual Patch are 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 patch executable (patch.exe) is perfect for distribution by web, email, LAN, CD-ROM or DVD-ROM.

100% Data Integrity

You can rest assured that patches are only applied to files you've specified. Using a combination of 128-bit MD5 hashing, CRC-32 checksums and industry standard data encryption protocols, Visual Patch helps you keep your applications and data safe from unauthorized use, transmission errors and other threats.

Automatic Target Detection

Visual Patch makes quick work out of locating your target application. Using a flexible combination of starting-point techniques (current folder, registry keys, file/folder searches) and key-file identification, Visual Patch can quickly locate the application files and folders on the system that require patching. Definitively identifying the target folder greatly simplifies the patching process and is a key requirement for ensuring that your software is updated quickly and correctly.

Customizable User Interface

Featuring a library of over twenty different screen templates, Visual Patch makes it easy to control your project's user interface. There are pre-built layouts to handle just about any task your can imagine, and it's easy to adjust them to fit your needs exactly. You'll find everything from check boxes, radio buttons and edit fields to popular screens like license agreements and folder selection. 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 results of your changes as you work.

Dynamic Interactive or Silent Operation

Visual Patch supports the creation of both fully-interactive "wizard based" patches or completely automatic "silent" patches that operate without displaying user interface dialogs, prompts and other messages. You can choose to dynamically enable the silent mode through a command line switch, or configure the patch to always run in this unattended mode. Either way, patches made with Visual Patch are suitable for use in both consumer/standalone applications and corporate/network patch management solutions.

Powerful Scripting Engine

Visual Patch includes an incredibly powerful free-form scripting engine, giving you unprecedented control over your software patching system. This easy to understand scripting language features everything from "for, repeat and while" loops, to "if/else" conditions, functions, variables and arrays. Paired with the built-in action library, full mathematical evaluation and Boolean expressions, there’s simply nothing you can't achieve. We've also built in an Action Wizard so even complete novices can create powerful projects that handle the most demanding patching tasks.

Comprehensive Action Library

To make the most out of Visual Patch scripting engine, we've included a library of over 250 high-level actions. With everything from registry editing to file copying to web file downloads, this complete scripting environment contains everything you need to automate complex tasks and handle even the most sophisticated software and system patching requirements. No other tool can match it!

Integrates with TrueUpdate

Visual Patch is an integral component of software lifecycle management. For a complete and fully integrated end-to-end solution, we'd recommend using Visual Patch in conjunction with Indigo Rose's Setup Factory (software installation) and TrueUpdate (automatic updating/patch delivery); however you’re certainly not locked into doing so. If your company has standardized on other tools for software installation, patch deployment and patch management, Visual Patch will still add significant benefit, being a best-of-breed solution.

Network Patch Management

Visual Patch isn't just for software vendors. It's also an extremely valuable tool for use in corporate, government and educational IT departments. Visual Patch helps you get the most out of your network patch management and software management/SMS infrastructure. As a network administrator responsible for keeping hundreds or thousands of computers and servers up to date, being able to create your own bullet-proof software patches is invaluable. Simply add them to your patch deployment solution of choice (TrueUpdate, SMS, etc) and manage them just like any other OS or application patch used on your network.

Trusted by Professionals

Thousands of companies trust Indigo Rose software tools. In fact our products, such as Setup Factory, TrueUpdate and AutoPlay Media Studio, are used to distribute and manage software on millions of customer and client systems around the world. Additionally, all of our products are backed up by world-class technical support services.


What's New in Visual Patch

Introduction

Contents What's New in Visual Patch

Visual Dialog Editor

One of your most asked for features is finally here. You now 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.

Vista / Windows 7 / Windows 8 / Windows 8.1 / Windows 10 Compatible

Visual Patch's design workspace and generated patches are compatible with Windows Vista, Windows 7, Windows 8, Windows 8.1 and Windows 10, including a configurable "requested execution level" setting for the patch's manifest. Other features enhanced for Vista/Windows 7/Windows 8/Windows 8.1/Windows 10 include: System.GetOSName, System.GetOSVersionInfo, System.GetUserInfo and File.Run actions, and file OS conditions.

Custom Resource Stamping

Visual Patch allows you to use your own product icon and provides full control of the version information that you want written into the patch's resources.

Integrated Code Signing

Protect the integrity of your company and products by code signing your patches with your own certificate during the build process.

Updated OS Conditions

Visual Patch now includes Windows Vista, Windows Server 2003 SP1 and SP2, Windows Server 2008, Windows 7 and Windows Server 2008 R2, Windows 8 and Windows Server 2012, Windows 8.1 and Windows Server 2012 R2, Windows 10 and Windows Server 10 in the list of file OS conditions.

Enhanced Design Performance

Reduced the loading time of the Visual Patch design environment and added additional memory preferences for the build process.

HTTP Action Enhancements

Made several enhancements to the HTTP actions for wider compatibility and increased stability.

Improved Workflow

Visual Patch features an unbeatable development environment that puts you in control of your files. Each point release gets its own version tab – then you simply drag and drop your files and folders onto the project window and you're ready to build. Visual Patch is smart enough to maintain your folder structure, automatically query version resource information, determine what has been added, changed or deleted and ensures 100% data integrity with reliable MD5 hashing and CRC-32 checksums.

Sophisticated Binary Patching Algorithm

Visual Patch features a cutting-edge binary differencing engine. By way of a sophisticated byte-granular analysis of your file data, Visual Patch is able to extract only the "delta" between one file version and the next. Rather than having to distribute a full copy of changed files, Visual Patch will only package up the parts that have changed. The result is a significant reduction in patch sizes, more security, reduced transmission time and lower bandwidth costs.

Project Wizard Quick-Start

Spend five minutes with Visual Patch's easy to use Project Wizard and come away with a complete and ready to build project. You'll be walked through each option so you can get your project started as quickly as possible. The new wizard helps you to add versions, associate your files, configure the user interface, and much more.

Customizable Wizard Dialogs

Visual Patch is extremely customizable. Included are over twenty different screen templates — easily adjustable to fit your particular needs — that handle just about any task your project requires. There's everything from check boxes, radio buttons and edit fields to popular screens like license agreements, folder selection and many more. 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.

Powerful Scripting Engine

Visual Patch includes the same scripting engine as Setup Factory, TrueUpdate and AutoPlay Media Studio. Based on the popular "Lua" language, this all-new and incredibly powerful free-form scripting engine gives you unprecedented control over your software patching system. This easy to use language features everything from "for, repeat and while" loops, to "if/else" conditions, functions, variables and associative arrays. Paired with the built-in action library, full mathematical evaluation and Boolean expressions, there is simply nothing you can't achieve. We've also built in an "Action Wizard" and "Quick Scripts" feature so you can get right up to speed creating powerful projects to handle even the most demanding tasks.

Extensive Action Library

Visual Patch includes a built-in library of more than 250 powerful, yet easy to use actions. There are high-level 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. Whatever you need your software patch to do, Visual Patch can make it happen!

Easy to Use Action Wizard

You don't have to be a wizard to create powerful patching systems with Visual Patch. 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!

Professional Script Editor

If you've outgrown the Action Wizard interface or simply want to get the most out of the Visual Patch scripting engine, we've got you covered. The Visual Patch 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.

Publishing Wizard

Once you've got your project ready to go, the Publishing Wizard will help you package it up into a compact single-file executable. Compare our tiny ~500 KB runtime overhead to the competition and see for yourself — patches created with Visual Patch extremely small and fast. What's more, the single-file patch executable is perfect for distribution by web, email, LAN, CD-ROM or DVD-ROM.

Themes, Skins and Backgrounds

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. If you like, you can even customize the desktop background with gradients, images, color washes, headlines and footer text with 3D effects.

Fully Automatic Patches

Visual Patch supports the creation of both fully-interactive "wizard based" patches or completely automatic "silent" patches. Silent patches operate without displaying user interface dialogs, prompts and other messages, making them perfect for use in corporate networks and managed infrastructures. New options let you enable silent operation via a command line switch, or even configure the patch to always run in unattended mode. Visual Patch patches automatically return command line status codes and are ready for use in automatic deployment processes and corporate patch management consoles.

Patch Security

Visual Patch includes a variety of features designed to help you manage access to your software, including the ability to ask for a serial number or password. Visual Patch automatically restricts use of your patch files through the use of binary differencing, key files and sophisticated message digests calculations.

Expandable with Action Plugins

Visual Patch can be easily expanded with Action Plugins. These add on modules can extend the product in infinitely powerful ways, such as adding support for databases, XML, data encryption and FTP file transfers. Tight integration with the design environment, including IntelliSense style code completion and syntax highlighting, makes Plugins 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 plug-in development kit.

International Language Support

Visual Patch gives you everything you need to support your customers and clients around the world. Patches created with Visual Patch 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, simply provide the text and Visual Patch takes care of the rest!

Built-in Spelling Checker

Now it's easier than ever to make sure that typos don't creep into your projects. Just about 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 patching project is now just a couple of clicks away. With improved HTML-based project reports (featuring CSS formatting) and text-based run-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 execution details.

Unattended Builds

Visual Patch fits seamlessly into your automated build processes. Software development teams and network managers will appreciate features such as build constants and pre/post build processes. You'll find that Visual Patch projects integrate right into your daily builds.

Works with Windows 95 and Up

Patches created with Visual Patch work just fine on every Windows operating system from Windows 95 to Windows 10. Compare that to competitive tools and you're sure to be surprised at their requirements. If you need to support legacy systems, your choice is clear!


Frequently Asked Questions

Introduction

Contents Frequently Asked Questions

Why use Visual Patch?

Visual Patch simplifies your product management and makes it easy to manage your software releases. There is no easier way to make professional quality, full-history patches for your software and other electronic content. Unlike other products, Visual Patch combines sophisticated binary patching with the flexibility offered by full-history patches. These patches can update any older version to the latest release with a single executable patch file.

Who needs Visual Patch?

Anyone who needs to create compact and secure software patches needs Visual Patch. This includes software developers, network administrators and IT managers, among others. Regardless of the type of data being distributed – executables, documents, databases, videos, etc. – Visual Patch can figure out what files have changed, the exact changes within each file and how to update any previous version to the current version.

How easy is it to learn?

Visual Patch's point-and-click design takes the difficulty out of building even the most sophisticated full-history patches. With the same ease of use and interface style that has made Setup Factory famous, Visual Patch makes it easier to get from "no patch" to "patch" than ever before.

How does Visual Patch affect my bottom line?

Distributing smaller files is good for both you and your customers. Visual Patch will help you save money on bandwidth, server hardware and network congestion. Your customers and clients will benefit from faster downloads, a reliable and easy to use patching process and increased satisfaction with your product and company.

Does Visual Patch support binary patching?

Yes. Visual Patch features state-of-the-art binary differencing and compression algorithms. Combined with a powerful full-history patching engine, Visual Patch offers a unique approach unequaled by any other product, making it an excellent addition to the toolbox of any software developer or IT manager.

Does Visual Patch support full history patching?

Yes. Visual Patch gives you full control over which versions of your software can be patched with a single executable. Unlike some other products, Visual Patch's full-history patching ability can update any version of your software to the latest release. This makes patches created with Visual Patch easier to apply and friendlier to use than those created with less sophisticated patch builders.

Can I password protect my patches?

Yes! Visual Patch includes a number of features designed to help you manage access to your software. Asking for a password or serial number is no problem. Additionally, Visual Patch automatically restricts use of your patch files through the use of binary differencing, key files and sophisticated message digests calculations.

Will my patch work on all Windows platforms?

Visual Patch builds patches with 100% support for all 32-bit Windows platforms. This includes Windows 95, 98, ME, NT4, 2000, XP, Vista, Windows 7, Windows 8, Windows 8.1, Windows 10, Server 2003, Server 2008, Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server 10.

What languages can my patch appear in?

Visual Patch gives you everything you need to support your customers and clients around the world. Patches created with Visual Patch 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, simply provide the text and Visual Patch takes care of the rest!

Why not just use Setup Factory to build a new installer?

When preparing a new release, you will certainly want to use Setup Factory to build an installer for new customers; however, you can save money and ensure the security of your updates by using patch files. Patch files are smaller as they only distribute the files that have changed and – more importantly – they are absolutely useless to anyone who doesn't already have a valid version of your software installed.

What’s the difference between an Installer builder and a Patch builder?

Installer builders (such as Indigo Rose's Setup Factory) have a different purpose than patch builders (like Visual Patch). A software installer is used to setup and configure a full software application on a computer system. Once it's installed and working, the installation program's job is done. In a perfect and unchanging world, that would be the end of the story. However, we all know that change is a constant. Software and data need to be updated periodically (bug fixes, features etc), but such changes seldom require the complete overhaul of a program. You need a method that synchronizes the data "in-the-field" with your current release.

Visual Patch greatly simplifies product maintenance by taking care of this for you. Whenever you have a new version ready, Visual Patch figures out what files need to be added, changed or replaced to bring any older version of your software up to date.

Visual Patch saves you time by making the design process as easy as possible. Visual Patch is also incredibly accurate; by automating much of the decision process, it eliminates opportunities for human error compared to developing patches "by hand" with other methods. Additionally, with the addition of binary differencing, Visual Patch can actually determine the areas of difference within a file and only distribute those particular changes – something that is impossible to do without sophisticated algorithms.

Will my patch be Internet ready?

Yes. Visual Patch generates a compact, single-file, self-executing patch that is easy to distribute, and easy for your users to use. It's perfect for distribution using web, email, LAN, TrueUpdate, CD-ROM or DVD-ROM. It’s also Authenticode-ready, so you can digitally sign your patches.

What other tools do I need to use Visual Patch?

None. As a standalone product, Visual Patch can be used by anyone. It doesn't matter what installation product you use or even whether you use one at all. If you need to get newer versions of files out to users, Visual Patch will do it. However, as part of a complete solution for software deployment, you will find that Visual Patch integrates quite nicely with tools like Setup Factory and TrueUpdate.

What kinds of files can Visual Patch update?

Visual Patch will work with any kind of files. You could even use it to update a few slides in a presentation, or individual files in a library of help documents used by your sales team. With a flexible tool like Visual Patch, the possibilities are endless.

Can I customize the runtime interface?

Yes. Visual Patch lets you easily drop in new wizard dialogs using the built-in Screen Manager and Gallery. Altering the display sequence is as simple as clicking on up and down arrows. You can edit text messages, use custom graphics and set conditional display options. A variety of screen types are available, from basic text displays, to check boxes, text input, radio buttons and more.

Can I create patches that target multiple operating systems?

Yes. You can attach conditions to any part of the patch to make them specific to the version of Windows that the user is running. For instance, your patch might install some new files only on Windows 95, or it might check different Registry locations for values if the user is running Windows 98 or Windows XP.

Can I distribute my patch on CD-ROM / DVD-ROM? Email? Web?

Yes. Visual Patch creates standalone, single-file executable patches that you can distribute using virtually any type of media you like.

Can Visual Patch handle advanced patching needs?

Absolutely. With Visual Patch, you aren't limited to just replacing old files with new ones. We've also included many advanced features – you can query the Registry, modify INI files, perform file searches, interact with web scripts, explore folders, delete and rename files, and more.

How does Visual Patch benefit the software developer?

The easier it is for your users to update your software, the more likely it is that your users will be using the latest version. As a result, your technical support team will have fewer legacy issues to deal with. The easier it is for you to release updates, the more often you can release them. You won't have to hold back releases until you have made enough changes to justify the effort required to prepare updates using traditional update methods.

How does Visual Patch impact technical support?

Timely software patches allow your users to benefit quickly from any new features and bug fixes you develop. Ensuring that users benefit from all the bug fixes you've released reduces the incidence of support calls. Keeping users up to date makes it easier to support them when incidents occur.

How will Visual Patch impact our customers and clients?

Today's users are savvy; they demand responsiveness from software companies and they want tools that meet their needs and make them more productive. In order to maintain customer loyalty and maximize the user's experience with your software, you need to make patching your software as easy as possible. Making it easy for users to patch your software shows that you're committed to supporting it.

How does Visual Patch benefit the network administrator?

Keeping a corporate, educational or government network up-to-date with the latest security patches, applications updates and operating system fixes is a time consuming ordeal. Without tools like Visual Patch, the task is virtually impossible. Used in conjunction with Indigo Rose's TrueUpdate, you'll be able to quickly and effectively roll out whatever software patches you need to throughout your organization. The TrueUpdate client software can analyze the computer system, decide what is currently installed and then take action to download and install the patches you've made with Visual Patch to bring that system up-to-date. It's fast, easy and automatic.

I'm not a developer...do I still need Visual Patch?

Absolutely! You don't need to be a software developer to benefit from Visual Patch. You can use Visual Patch to update product catalogs, databases, price lists, help files, quarterly reports, training videos or whatever else you want.


The Visual Patch Interface

Introduction

Contents The Visual Patch Interface

The Visual Patch 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 version file lists, which is where all the files in each version of your project are listed. The number of version lists depends upon how many versions you have for your software. You can switch between each version's 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.


Importing Visual Patch 1.0 Projects

Introduction

Contents Importing Visual Patch 1.0 Projects

Introduction

Visual Patch 2.0/3.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 v1.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 patch, multilingual patches have never been easier to manage. Instead of having to include a new screen for each language in your project, you can now manage all language translations on each screen. Another exciting feature available in version is the addition of our state-of-the-art binary differencing and compressions algorithms. The result is a smaller and better performing software patch.

As a result, the conversion of projects created with v1.0 is not a fully automated process. In general, your versions and file listings will be converted automatically, however some of the file properties have been simplified, therefore they may not all exist. Areas that are not converted include all of your actions, screens, project settings etc.

Converting Projects from v1.0 to v3.0

Given that Visual Patch will only convert your version file lists, you may find it just as easy to create a new project in version using the new Project Wizard. The only reason that you may want to import the version file lists is if you have a large number of versions, or have customized the source and destination paths to a great extent. In most cases, we recommend starting your projects from scratch.

To import your project, simply go to File > Open..., select "Visual Patch 1.0 Files (*.vp1) from the Files of type dropdown and select your Visual Patch 1.0 project file. The conversion tool will take over and bring over your version data given the available options in Visual Patch.

Where Do I Go Next?

The first section to read in the help file should be the Key Features of Visual Patch section. This will help point out all of the new and exciting features available. The next section to take a look at is the topic The Visual Patch 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 have some underlying questions about Visual Patch, take a look at the Frequently Asked Questions topic. It answers many common questions that developers have about the program.

If you are still not sure how things work in Visual Patch, 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. You can access the User's Guide from the Help program menu.

If you are planning to recreate an existing patch, before attempting to translate your actions into Visual Patch scripts, you should read over the Scripting Guide. This guide will provide you with tips, tricks, and professional-level techniques you should use when writing your Visual Patch scripts.


Patching On Windows Vista

Patching On Windows Vista or Later

Windows Vista

Overview

In general patches and applications designed for Windows XP are highly compatible with Windows Vista and 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 and Later 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 applications 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 and 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 (Visual Patch patches are always 32-bit).

New Visual Patch Vista / Windows 7 / Windows 8 / Windows 8.1 / Windows 10 Runtime Features

Several new features have been added to aid in the patching 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 single and multiple file patch conditions found on the Conditions tab of the single or multiple file/folder reference properties dialog.

  • Patch application manifests containing configurable requested execution level settings. The Requested User Privilege Level setting can be found in on the "Advanced" tab of Project > 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/Windows 8/Windows 8.1/Windows 10/Server 2008/Server 2008 R2/Server 2012/Server 2012 R2/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 patches with your certificate. You can find these settings on the Code Signing tab of the "Build Settings" dialog (Publish > Settings).

Changing the "Requested User Privilege Level" Setting

The Requested User Privilege Level setting specifies which requested execution level to include in the patch's application manifest for distribution on Windows Vista or later. When the patch is run, the operating system reads this information to identify what privileges it requires. The default setting in Visual Patch is "Require administrator" and should generally never be changed. If for some reason you do not want to require administrator privileges to run the patch given its content, you should be aware of the following information and required changes:

Changing to "As invoker"

Using the "As invoker" setting means that your patch 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 patch 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 the Windows 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 patch 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 and 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.

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 patch is designed to be run by all users. The patch runs with the same access token as the parent process. This means that if the patch 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 patch, 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 patch performs administrator tasks, the "Require administrator" option should be used in addition to the usual administrator detection and conditions.

Previously Created Patches

Patches are now properly manifested using the Requested User Privilege Level setting. Patches created using a previous release may encounter some compatibility problems. However, Windows Vista and later contains a new "Installer Detection" feature that automatically detects unmanifested Visual Patch patches as an "installer type." This will automatically prompt the user for elevation or logon credentials.

Note: While the Windows Vista and later "Detect application installation and prompt for elevation" setting is enabled by default, it can be turned off. If this setting was disabled, the patch 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 patches to be Windows Vista or later compliant, we strongly recommend publishing the patch again using in the current version of Visual Patch.

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 Windows Vista and later has the ability to prevent any unsigned application from launching with full privileges. This may impact both the patch and application functionality. It is recommended that all application and patch files be signed when distributed on Windows Vista or later.

Note: For more information, see Authenticode Code Signing.


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

Visual Patch 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 © 2001-2015 Indigo Rose Software Design Corporation.
All Rights Reserved.

LUA is copyright © 2003-2015 Tecgraf, PUC-Rio.


Ordering Information

Ordering Information

Benefits of Ordering

When you order Visual Patch you will receive:

  • Visual Patch program with the latest revisions and enhancements.

  • A license to distribute, royalty-free, the patches that you create with Visual Patch.

  • A professionally written electronic User's Guide (PDF format) and Program Reference.

Please visit www.indigorose.com for available support resources and policies.

Pricing

Current pricing information can be obtained from our web site at www.indigorose.com.

Visual Patch 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.


Printed Manuals

Ordering Printed Manuals

A professionally printed, perfect-bound version of the User's Guide is available from www.ondemandmanuals.com.

Visual Patch User's Guide:

Pages: 280+

About the Manual

The printed versions are provided for registered users exclusively through www.ondemandmanuals.com. All of the manuals are printed on demand as orders are received, from computer files that Indigo Rose Software updates with revisions and error corrections as often as required. This ensures that the printed copy of the manual you receive will be as up-to-date and free of errors as possible.

Note that printed manuals are ordered directly from www.ondemandmanuals.com and Indigo Rose Software has no control over the shipping costs or what shipping methods are available.

PDF Format

If you would prefer to print the documentation yourself, the Visual Patch User's Guide is included with the product in Adobe Acrobat (PDF) format. You can access this resource from the Start menu.


System Requirements

Overview

Design Environment

The minimum system requirements for the Visual Patch design environment are:

Note: Generating patches is highly dependant on the amount of memory as well as processor speed. Results also vary with the size of the files that a patch is being created for. To achieve the best possible patches with Visual Patch, we recommend not running other applications in the background while generating your patch executables.

Minimum

Windows XP SP2, Vista, Windows 7, Windows 8, Windows 8.1 or Windows 10
Celeron 500 MHz
128 MB RAM
800x600 SVGA display with small fonts setting enabled
20+ MB free hard drive space
Video card set to 16 bit color or greater
Internet Explorer 4.0 or greater
Mouse

Run-time Application (Built Patch)

The minimum system requirements for the patches generated by Visual Patch are:

Minimum

Windows 95B and up (including Windows 10)
486 processor
32 MB RAM
640x480 SVGA display
Video card set to 8 bit 256 color or greater (recommended)
10+ MB free hard drive space

Note: The following HTTP actions require Internet Explorer 4.0 or greater: HTTP.GetConnectionState, HTTP.DownloadSecure and HTTP.SubmitSecure.


Introduction

Visual Patch is a fast and efficient system for creating software patches. This unique solution features state-of-the-art binary differencing and compression algorithms, combined with a powerful full-history patching engine. Visual Patch makes an excellent addition to the toolbox of any software developer or IT manager.

In Visual Patch, we’ve improved the development environment to streamline your workflow and continued the unprecedented flexibility of the scripting engine and action library. We’ve also maintained a customizable screen manager, project themes (skins), action plugins, MD5 security, and many other powerful and timesaving features.

You’ll find that Visual Patch simplifies software version management. It turns the otherwise complicated task of managing point-releases into a fast and automated process. There is no easier way to make professional-quality, full-history binary patches for your software and other electronic content.

What is Visual Patch?

It doesn’t matter what kind of electronic content you’re distributing. Whether it’s application software, databases, spreadsheets, video, audio or any other data, the likelihood is that it will change over time. That’s why you need Visual Patch.

Visual Patch makes it easy to create professional, rock-solid software patches. As you release new software (documents, data, etc.), simply drag-and-drop the files into Visual Patch and it will automatically track and package the differences for you.

Using a sophisticated combination of binary differencing, data compression and MD5 fingerprinting, Visual Patch is able to create compact full-history software patches that outperform any comparable tool on a value and feature-by-feature basis.

Visual Patch is an integral part of a complete and effective approach to software lifecycle management. Software developers, network administrators and IT departments all require a professional tool for building software patches. As such, Visual Patch integrates seamlessly with other Indigo Rose products like Setup Factory (software installation) and TrueUpdate (automated updating/patch delivery) to provide a complete solution for all aspects of software delivery.

Key Features of Visual Patch

Vista / Windows 7 / Windows 8 / Windows 8.1 / Windows 10 Compatible

Visual Patch's design workspace and generated patches are compatible with Windows Vista, Windows 7, Windows 8, Windows 8.1 and Windows 10, including a configurable "requested execution level" setting for the patch's manifest.

Custom Resource Stamping

Visual Patch allows you to use your own product icon and provides full control of the version information that you want written into the patch's resources.

Integrated Code Signing

Protect the integrity of your company and products by code signing your patches with your own certificate during the build process.

Sophisticated Version Management

Visual Patch makes it easy to manage your software releases. You can quickly and easily add, remove and organize product versions, and see all of the important details about your files. The toolbars, columns, sort-order, color-coding and other interface elements are fully customizable, allowing you to view only the information that is important to your workflow.

State-of-the-Art Binary Differencing Engine

Visual Patch features state-of-the-art binary differencing and compression algorithms. This ensures smaller and better performing software patches. The algorithms used by Visual Patch were developed specifically for their impressive speed characteristics. Whereas software patching was once a notoriously slow and cumbersome process, companies choosing Visual Patch have a distinct advantage.

Full-History Patching

With Visual Patch, you have full control over which versions of your software can be patched with a single executable. While some vendors will choose to include only a single version update, others may offer a patch that can update any version that has ever been released. Visual Patch can handle either extreme, or anything in between. Unlike some other products, Visual Patch’s full-history patching ability can update any version of your software to the latest release. By only having one file to download, Visual Patch brand patches are much more user friendly. Your users won’t have to worry about finding multiple patches and applying them in the correct order as they would if you used other, less sophisticated patch builders.

Internet Ready, Single-File Executable

Smaller and faster means a better experience for your customers, and Visual Patch delivers. Compare our tiny ~500 KB runtime overhead to the competition and see for yourself. Patches created with Visual Patch are 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 patch executable (patch.exe) is perfect for distribution by web, email, LAN, CD-ROM or DVD-ROM.

100% Data Integrity

You can rest assured that patches are only applied to files you’ve specified. Using a combination of 128-bit MD5 hashing, CRC-32 checksums and industry standard data encryption protocols, Visual Patch helps you keep your applications and data safe from unauthorized use, transmission errors and other threats.

Automatic Target Detection

Visual Patch makes quick work out of locating your target application. Using a flexible combination of starting-point techniques (registry keys and file/folder searches) and key-file identification, Visual Patch can quickly locate the application files and folders on the system that require patching. Definitively identifying the target folder greatly simplifies the patching process and is a key requirement for ensuring that your software is updated quickly and correctly.

Customizable User Interface

Featuring a library of over twenty different screen templates, Visual Patch makes it easy to control your project's user interface. There are pre-built layouts to handle just about any task you can imagine, and it's easy to adjust them to fit your needs exactly. You'll find everything from check boxes, radio buttons and edit fields to popular screens like license agreements and folder selection. 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 results of your changes as you work.

Dynamic Interactive or Silent Operation

Visual Patch supports the creation of both fully-interactive "wizard based" patches or completely automatic "silent" patches that operate without displaying user interface dialogs, prompts and other messages. You can choose to dynamically enable the silent mode through a command line switch, or configure the patch to always run in this unattended mode. Either way, patches made with Visual Patch are suitable for use in both consumer/standalone applications and corporate/network patch management solutions.

Powerful Scripting Engine

Visual Patch includes an incredibly powerful free-form scripting engine, giving you unprecedented control over your software patching system. This easy to understand scripting language features everything from "for, repeat and while" loops, to "if/else" conditions, functions, variables and arrays. Paired with the built-in action library, full mathematical evaluation and Boolean expressions, there’s simply nothing you can’t achieve. We’ve also built in an Action Wizard so even complete novices can create powerful projects that handle the most demanding patching tasks.

Comprehensive Action Library

To make the most out of Visual Patch scripting engine, we’ve included a library of over 250 high-level actions. With everything from registry editing to file copying to web file downloads, this complete scripting environment contains everything you need to automate complex tasks and handle even the most sophisticated software and system patching requirements. No other tool can match it!

Integrates with TrueUpdate

Visual Patch is an integral component of software lifecycle management. For a complete and fully integrated end-to-end solution, we’d recommend using Visual Patch in conjunction with Indigo Rose’s Setup Factory (software installation) and TrueUpdate (automatic updating/patch delivery); however you’re certainly not locked into doing so. If your company has standardized on other tools for software installation, patch deployment and patch management, Visual Patch will still add significant benefit, being a best-of-breed solution.

Network Patch Management

Visual Patch isn’t just for software vendors. It’s also an extremely valuable tool for use in corporate, government and educational IT departments. Visual Patch helps you get the most out of your network patch management and software management/SMS infrastructure. As a network administrator responsible for keeping hundreds or thousands of computers and servers up to date, being able to create your own bulletproof software patches is invaluable. Simply add them to your patch deployment solution of choice (TrueUpdate, SMS, etc) and manage them just like any other OS or application patch used on your network.

Trusted by Professionals

Thousands of companies trust Indigo Rose software tools. In fact our products, such as Setup Factory, TrueUpdate and AutoPlay Media Studio, are used to distribute and manage software on millions of customer and client systems around the world. Additionally, all of our products are backed up by world-class technical support services.

What’s New in Visual Patch?

Vista / Windows 7 / Windows 8 / Windows 8.1 / Windows 10 Compatible

Visual Patch's design workspace and generated patches are compatible with Windows Vista, Windows 7, Windows 8, Windows 8.1 and Windows 10, including a configurable "requested execution level" setting for the patch's manifest. Other features enhanced for Vista/Windows 7/Windows 8/Windows 8.1/Windows 10 include: System.GetOSName, System.GetOSVersionInfo, System.GetUserInfo and File.Run actions, and file OS conditions.

Custom Resource Stamping

Visual Patch allows you to use your own product icon and provides full control of the version information that you want written into the patch's resources.

Integrated Code Signing

Protect the integrity of your company and products by code signing your patches with your own certificate during the build process.

Updated OS Conditions

Visual Patch now includes Windows Vista, Windows Server 2003 SP1 and SP2, Windows Server 2008, Windows 7, Windows Server 2008 R2, Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 and Windows Server 10 in the list of file OS conditions.

Enhanced Design Performance

Reduced the loading time of the Visual Patch design environment and added additional memory preferences for the build process.

HTTP Action Enhancements

Made several enhancements to the HTTP actions for wider compatibility and increased stability.

Improved Workflow

Visual Patch features an unbeatable development environment that puts you in control of your files. Each point release gets its own version tab – then you simply drag and drop your files and folders onto the project window and you’re ready to build. Visual Patch is smart enough to maintain your folder structure, automatically query version resource information, determine what has been added, changed or deleted and ensures 100% data integrity with reliable MD5 hashing and CRC-32 checksums.

Sophisticated Binary Patching Algorithm

Visual Patch features a cutting-edge binary differencing engine. By way of a sophisticated byte-granular analysis of your file data, Visual Patch is able to extract only the "delta" between one file version and the next. Rather than having to distribute a full copy of changed files, Visual Patch will only package up the parts that have changed. The result is a significant reduction in patch sizes, more security, reduced transmission time and lower bandwidth costs.

Project Wizard Quick-Start

Spend five minutes with Visual Patch’s easy to use Project Wizard and come away with a complete and ready to build project. You’ll be walked through each option so you can get your project started as quickly as possible. The new wizard helps you to add versions, associate your files, configure the user interface, and much more.

Customizable Wizard Dialogs

Visual Patch is considerably more customizable than before. Included are over twenty different screen templates - easily adjustable to fit your particular needs - that handle just about any task your project requires. There's everything from check boxes, radio buttons and edit fields to popular screens like license agreements, folder selection and many more. 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.

Powerful Scripting Engine

Visual Patch includes the same scripting engine as Setup Factory, TrueUpdate, and AutoPlay Media Studio. Based on the popular "Lua" language, this all-new and incredibly powerful free-form scripting engine gives you unprecedented control over your software patching system. This easy to use language features everything from "for, repeat and while" loops, to "if/else" conditions, functions, variables and associative arrays. Paired with the built-in action library, full mathematical evaluation and Boolean expressions, there is simply nothing you can’t achieve. We’ve also built in an "Action Wizard" and "Quick Scripts" feature so you can get right up to speed creating powerful projects to handle even the most demanding tasks.

Extensive Action Library

Visual Patch includes a built-in library of more than 250 powerful, yet easy to use actions. There are high-level 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. Whatever you need your software patch to do, Visual Patch can make it happen!

Easy to Use Action Wizard

You don’t have to be a wizard to create powerful patching systems with Visual Patch. 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!

Professional Script Editor

If you’ve outgrown the Action Wizard interface or simply want to get the most out of the Visual Patch scripting engine, we’ve got you covered. The Visual Patch 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.

Publishing Wizard

Once you’ve got your project ready to go, the Publishing Wizard will help you package it up into a compact single-file executable. Compare our tiny ~500 KB runtime overhead to the competition and see for yourself - patches created with Visual Patch are smaller and faster than ever before. What’s more, the single-file patch executable is perfect for distribution by web, email, LAN, CD-ROM or DVD-ROM.

Themes, Skins and Backgrounds

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. If you like, you can even customize the desktop background with gradients, images, color washes, headlines and footer text with 3D effects.

Fully Automatic Patches

Visual Patch supports the creation of both fully-interactive "wizard based" patches or completely automatic "silent" patches. Silent patches operate without displaying user interface dialogs, prompts and other messages, making them perfect for use in corporate networks and managed infrastructures. New options let you enable silent operation via a command line switch, or even configure the patch to always run in unattended mode. Visual Patch patches automatically return command line status codes and are ready for use in automatic deployment processes and corporate patch management consoles.

Patch Security

Visual Patch includes a variety of features designed to help you manage access to your software, including the ability to ask for a serial number or password. Visual Patch automatically restricts use of your patch files through the use of binary differencing, key files and sophisticated message digests calculations.

Expandable with Action Plugins

Visual Patch can be easily expanded with Action Plugins. These add on modules can extend the product in infinitely powerful ways, such as adding support for databases, XML, data encryption and FTP file transfers. Tight integration with the design environment, including IntelliSense style code completion and syntax highlighting, makes Plugins 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 plug-in development kit.

International Language Support

Visual Patch gives you everything you need to support your customers and clients around the world. Patches created with Visual Patch 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, simply provide the text and Visual Patch takes care of the rest!

Built-in Spelling Checker

Now it’s easier than ever to make sure that typos don’t creep into your projects. Just about 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 patching project is now just a couple of clicks away. With improved HTML-based project reports (featuring CSS formatting) and text-based run-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 execution details.

Unattended Builds

Visual Patch fits seamlessly into your automated build processes. Software development teams and network managers will appreciate features such as build constants and pre/post build processes. You’ll find that Visual Patch projects integrate right into your daily builds.

Works with Windows 95 and Up

Patches created with Visual Patch work just fine on every Windows operating system from Windows 95 to Windows 10. Compare that to competitive tools and you’re sure to be surprised at their requirements. If you need to support legacy systems, your choice is clear!

Frequently Asked Questions

Why use Visual Patch?

Visual Patch simplifies your product management and makes it easy to manage your software releases. There is no easier way to make professional quality, full-history patches for your software and other electronic content. Unlike other products, Visual Patch combines sophisticated binary patching with the flexibility offered by full-history patches. These patches can update any older version to the latest release with a single executable patch file.

Who needs Visual Patch?

Anyone who needs to create compact and secure software patches needs Visual Patch. This includes software developers, network administrators and IT managers, among others. Regardless of the type of data being distributed – executables, documents, databases, videos, etc. – Visual Patch can figure out what files have changed, the exact changes within each file and how to update any previous version to the current version.

How easy is it to learn?

Visual Patch's point-and-click design takes the difficulty out of building even the most sophisticated full-history patches. With the same ease of use and interface style that has made Setup Factory famous, Visual Patch makes it easier to get from "no patch" to "patch" than ever before.

How does Visual Patch affect my bottom line?

Distributing smaller files is good for both you and your customers. Visual Patch will help you save money on bandwidth, server hardware and network congestion. Your customers and clients will benefit from faster downloads, a reliable and easy to use patching process and increased satisfaction with your product and company.

Does Visual Patch support binary patching?

Yes. Visual Patch features state-of-the-art binary differencing and compression algorithms. Combined with a powerful full-history patching engine, Visual Patch offers a unique approach unequaled by any other product, making it an excellent addition to the toolbox of any software developer or IT manager.

Does Visual Patch support full history patching?

Yes. Visual Patch gives you full control over which versions of your software can be patched with a single executable. Unlike some other products, Visual Patch’s full-history patching ability can update any version of your software to the latest release. This makes patches created with Visual Patch easier to apply and friendlier to use than those created with less sophisticated patch builders.

Can I password protect my patches?

Yes. Visual Patch includes a number of features designed to help you manage access to your software. Asking for a password or serial number is no problem. Additionally, Visual Patch automatically restricts use of your patch files through the use of binary differencing, key files and sophisticated message digests calculations.

Will my patch work on all Windows platforms?

Visual Patch builds patches with 100% support for all 32-bit Windows platforms. This includes Windows 95, 98, ME, NT4, 2000, XP, Vista, Windows 7, Windows 8, Windows 8.1, Windows 10, Server 2003, Server 2008, Server 2008 R2 and Server 2012, Server 2012 R2, Windows Server 10.

What languages can my patch appear in?

Visual Patch gives you everything you need to support your customers and clients around the world. Patches created with Visual Patch 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, simply provide the text and Visual Patch takes care of the rest!

Why not just use Setup Factory to build a new installer?

When preparing a new release, you will certainly want to use Setup Factory to build an installer for new customers; however, you can save money and ensure the security of your updates by using patch files. Patch files are smaller as they only distribute the files that have changed and – more importantly – they are absolutely useless to anyone who doesn't already have a valid version of your software installed.

What’s the difference between an Installer builder and a Patch builder?

Installer builders (such as Indigo Rose’s Setup Factory) have a different purpose than patch builders (like Visual Patch). A software installer is used to setup and configure a full software application on a computer system. Once it’s installed and working, the installation program’s job is done. In a perfect and unchanging world, that would be the end of the story. However, we all know that change is a constant. Software and data need to be updated periodically (bug fixes, features etc), but such changes seldom require the complete overhaul of a program. You need a method that synchronizes the data "in-the-field" with your current release.

Visual Patch greatly simplifies product maintenance by taking care of this for you. Whenever you have a new version ready, Visual Patch figures out what files need to be added, changed or replaced to bring any older version of your software up to date.

Visual Patch saves you time by making the design process as easy as possible. Visual Patch is also incredibly accurate; by automating much of the decision process, it eliminates opportunities for human error compared to developing patches "by hand" with other methods. Also, with the addition of binary differencing, Visual Patch can actually determine the areas of difference within a file and only distribute those particular changes – something that is impossible to do without sophisticated algorithms.

Will my patch be Internet ready?

Yes. Visual Patch generates a compact, single-file, self-executing patch that is easy to distribute, and easy for your users to use. It’s perfect for distribution using web, email, LAN, TrueUpdate, CD-ROM or DVD-ROM. It’s also Authenticode-ready, so you can digitally sign your patches.

What other tools do I need to use Visual Patch?

None. As a standalone product, Visual Patch can be used by anyone. It doesn't matter what installation product you use or even whether you use one at all. If you need to get newer versions of files out to users, Visual Patch will do it. However, as part of a complete solution for software deployment, you will find that Visual Patch integrates quite nicely with tools like Setup Factory and TrueUpdate.

What kinds of files can Visual Patch update?

Visual Patch will work with any kind of files. You could even use it to update a few slides in a presentation, or individual files in a library of help documents used by your sales team. With a flexible tool like Visual Patch, the possibilities are endless.

Can I customize the runtime interface?

Yes. Visual Patch lets you easily drop in new wizard dialogs using the built-in Screen Manager and Gallery. Altering the display sequence is as simple as clicking on up and down arrows. You can edit text messages, use custom graphics and set conditional display options. A variety of screen types are available, from basic text displays, to check boxes, text input, radio buttons and more.

Can I create patches that target multiple operating systems?

Yes. You can attach conditions to any part of the patch to make them specific to the version of Windows that the user is running. For instance, your patch might install some new files only on Windows 95, or it might check different Registry locations for values if the user is running Windows 98 or Windows XP.

Can I distribute my patch on CD-ROM / DVD-ROM? Email? Web?

Yes. Visual Patch creates standalone, single-file executable patches that you can distribute using virtually any type of media you like.

Can Visual Patch handle advanced patching needs?

Absolutely. With Visual Patch, you aren't limited to just replacing old files with new ones. We've also included many advanced features – you can query the Registry, modify INI files, perform file searches, interact with web scripts, explore folders, delete and rename files, and more.

How does Visual Patch benefit the software developer?

The easier it is for your users to update your software, the more likely it is that your users will be using the latest version. As a result, your technical support team will have fewer legacy issues to deal with. The easier it is for you to release updates, the more often you can release them. You won't have to hold back releases until you have made enough changes to justify the effort required to prepare updates using traditional update methods.

How does Visual Patch impact technical support?

Timely software patches allow your users to benefit quickly from any new features and bug fixes you develop. Ensuring that users benefit from all the bug fixes you've released reduces the incidence of support calls. Keeping users up to date makes it easier to support them when incidents occur.

How will Visual Patch impact our customers and clients?

Today's users are savvy; they demand responsiveness from software companies and they want tools that meet their needs and make them more productive. In order to maintain customer loyalty and maximize the user's experience with your software, you need to make patching your software as easy as possible. Making it easy for users to patch your software shows that you're committed to supporting it.

How does Visual Patch benefit the network administrator?

Keeping a corporate, educational or government network up-to-date with the latest security patches, applications updates and operating system fixes is a time consuming ordeal. Without tools like Visual Patch, the task is virtually impossible. Used in conjunction with Indigo Rose’s TrueUpdate, you’ll be able to quickly and effectively roll out whatever software patches you need to throughout your organization. The TrueUpdate client software can analyze the computer system, decide what is currently installed and then take action to download and install the patches you’ve made with Visual Patch to bring that system up-to-date. It’s fast, easy and automatic.

I'm not a developer...do I still need Visual Patch?

Absolutely! You don't need to be a software developer to benefit from Visual Patch. You can use Visual Patch to update product catalogs, databases, price lists, help files, quarterly reports, training videos or whatever else you want.


Chapter 1: Understanding Visual Patch

User's Guide - Chapter 1: Understanding Visual Patch

Understanding Visual Patch

Patching software from one version to another is a sophisticated process.

Visual Patch is designed to make the patching process as simple to understand as possible. It takes care of most details for you, such as inspecting your versions to decide which files have changed, and analyzing the individual files in each version in order to extract the differences between them.

However, there are some important concepts that you will want to understand before you begin designing your first patch. Some of these, like the concept of key files, are unique to Visual Patch and are central to how the patching system works.

This chapter will discuss the nature of patching and explain some of the concepts you need to know in order to use Visual Patch effectively.

What is a Patch?

A patch is a file that, when run, modifies or replaces specific files on a computer system, usually to bring an already-installed software product up to date.

Patches are used every day to fix problems, add features, solve unforeseen compatibility issues, and fix security holes. They can be used to update all kinds of files: software executables, word documents, satellite images, medical databases, ocean maps, game data files, even parts of the operating system itself.

Because they only contain the data that has changed, patches are also used to transmit changes to very large files as efficiently and securely as possible.

Benefits of Patching

The role of patches in the software deployment cycle is to get already-installed software up to date after it becomes outdated. Patching technology offers numerous benefits over simply redistributing new versions of the original software in whole form.

Smaller file size

Because they only contain the data that has changed from one version to another, patches can be much smaller than a full software installer needs to be. Especially in situations where large data files are involved, the savings are often dramatic-patches that are less than 1% of the original file sizes are possible.

Reduced traffic

Smaller file sizes translate into reduced bandwidth costs, and reducing the amount of traffic leaves more bandwidth for other services.

Faster transmission speeds

Having less data to transmit means that updates can be sent and received faster, which means less time is spent waiting for updates.

Security

The best way to protect information during transmission is to never transmit it in the first place. By only transmitting the data that has changed, patches reduce the risk of third-party interception. Even if some hypothetical future technology made it possible to "crack" the encryption methods used to package the changes, the unchanged data would remain safe.

Integrity

A patch can’t update something that isn’t there. If a user doesn’t already have your software installed, they won’t be able to apply the patch. And if someone is using a modified version of a file, that file won’t be updated-unless you expressly permit it when you design your patch.

What Can a Patch Do?

The basic role of a patch is to modify or replace files so they match the files in a target version of your software. It also might need to back up or remove any legacy files, i.e. files from previous versions that no longer exist in the current version.

But Visual Patch isn’t limited to just updating files. With a built-in scripting engine containing over 250 high-level actions, it can also perform many other tasks involving everything from Registry changes to HTTP downloads.

With a little bit of scripting, your patch application can handle any advanced task you need it to: copying files, modifying INI files, starting and stopping services-even calling external DLL functions.

This ability to perform system changes in addition to the basic file updating is an important and valuable feature of Visual Patch.

Tip: If you use Setup Factory to build your software installer, you can use actions to add new files to the uninstall control file so they will be removed along with the original files when the user uninstalls your software via the control panel.

Patching Methods

There are two basic methods that can be used to update a file: binary patching, and whole-file patching.

Binary Patching

Binary patching or "delta compression" involves analyzing two versions of a file in order to extract only the data that has changed. The same changes can then be applied to any file that matches the old version, in order to "transform" it into the new version.

Creating a binary patch involves performing a byte-by-byte comparison between the original file and the new file, and then encoding the differences into a difference file. Each difference file contains the actual bytes that are different in the new file, along with a number of instructions that describe which bytes need to change, and which bytes are the same. This information is said to be encoded into the difference file.

Tip: The term "difference file" is often shortened to "diff file" or just "diff."

When the patch is applied, the difference file is decoded, and the instructions are used to build the new file by copying the "unchanged" data out of the old file, along with the "changed" data that was encoded into the difference file.

For example, given an old file "A" and a new file "B," a binary patching engine would compare A to B and then produce a difference file; let’s call it "AB.diff." Once the difference file is created, you can use it to create the B file from any file that matches the A file. In fact, the binary patching engine could recreate B using A and AB.diff.

Because binary patching only stores the parts that have changed, the difference files can be very small-often less than one percent of the new file’s size. The size of the difference file depends entirely on how much data has changed between the two versions.

Each difference file can update a single, specific version of a file to another single, specific version of that file. The encoded instructions in the difference file are only valid for a file that is a perfect match of the original source file. Note that binary patching cannot be used to update a file if it has been modified in any way.

For patches that need to update multiple files, the patch executable will need to contain a separate difference file for each file that needs to be updated. So, for example, to update a single file from version 1.0 or 1.1 to version 1.2, using a single patch executable, it would need to contain one difference file to go from 1.0 to 1.2, and another to go from 1.1 to 1.2.

In most cases, the difference files are so small that you can fit a lot of versions into a single patch executable and still use less space than you would by just including the whole file, as in whole-file patching (see below).

Note: Visual Patch will automatically switch from binary to whole-file patching on a file-by-file basis whenever the total size of all the difference files surpasses the size of the whole file.

In some cases, encoding the differences between the two files results in a binary patch that is larger than just compressing the new file, for example into a .zip archive. This generally means that there are very little similarities between the two files; in other words, the two files are so different that it is difficult to reuse any of the data in the old file. This can sometimes be the case for files that are already highly compressed, or files that are encrypted. Visual Patch is able to detect these cases and will choose whichever patching method provides the best results.

Whole-File Patching

Whole-file patching operates on a different principle. Instead of only containing the parts that have changed (as binary patches do), whole-file patches just copy the entire file. The "patch" is just a copy of the new version.

Whole-file patches can be faster to apply, because they don't have to search through the original file in order to copy the parts that haven’t changed to the new version. They just overwrite the old file with the new one. The downside, of course, is that whole-file patches tend to be much larger than binary patches.

There are, however, two situations where whole-file patches can actually be smaller: when creating a single patch file that is able to update many different versions, and when the files being patched are too dissimilar.

Visual Patch always chooses the patching method that produces the best results. It automatically switches between binary patching and whole-file patching on a file-by-file basis in order to produces the smallest patch possible for your project.

Patching Strategies

Although Visual Patch chooses the right patching method for every situation, it’s up to you to choose an overall patching strategy. The three general strategies that you can choose from relate to the three different "kinds" of patches you can create.

Visual Patch supports three general patching strategies: incremental patching, multi-version patching, and full-history patching.

Incremental Patching

An incremental patch is a patch that is able to update a single, specific version to a single target version. For example, a patch that is able to update version 1.3 to 1.4, and only 1.3 to 1.4, is an incremental patch. Similarly, a patch that is able to update version 1.0 to 1.4, and only 1.0 to 1.4, is an incremental patch.

Incremental patches take full advantage of binary patching. Each patch only needs to contain a single difference file for each file that has changed. This eliminates any unnecessary data in the patch. For example, why bother sending the data needed to update 1.0 to 1.4 if the user has 1.3 installed? Because an incremental patch is targeted at a specific version, it only needs to contain the information needed to update that version, and nothing else.

This is especially true for incremental patches that update two consecutive versions. Although there may be many changes over the entire history of a software product, the changes between any two consecutive versions are typically very small. For example, if there are files that changed from version 1.2 to 1.3, but these files didn’t change from version 1.3 to 1.4, an incremental patch to go from 1.3 to 1.4 doesn’t need to contain any data for the files that changed from 1.2 to 1.3. This minimizes the amount of data that needs to be included in the patch.

Incremental patching generates the smallest and most secure patches possible.

Multi-Version Patching

A multi-version patch, as the name implies, is a patch that is able to update multiple installed versions to a single target version. For example, a patch that is able to update versions 1.2 and 1.3 to 1.4 is a multi-version patch.

Multi-version patches are larger than incremental patches. The more versions that a patch supports, the more information it needs to contain. This increases the amount of redundant data within the patch.

When a user runs the patch, they are only interested in updating a single version: the one they currently have installed on their system. All of the other versions that a multi-version patch supports are just excess baggage for that user.

The benefit of multi-version patches is that they are simpler to coordinate. A single patch file can be used to update multiple versions. Your users have fewer patches to choose from, and you have fewer patches to distribute. If there are 15 different versions of your software in the field, you would need 15 incremental patches to support them all. Using multi-version patches allows you to support all 15 potentially installed versions with fewer patches.

Full-History Patching

A full-history patch is able to update every previous release of your software up to a single target version. It is essentially a multi-version patch for every version of your software.

Full-history patches are the simplest patches to coordinate since the same patch file can update all versions of your software. Your users don’t have to know what version they currently have in order to choose the correct patch. You only have to provide a single download that will work for all of your users. It’s simple, straightforward, and uncomplicated.

However, full-history patches are the largest patches you can produce. In some cases they can even approach or surpass the size of a full install. For this reason, you will want to weigh the benefits of full-history patching vs. the other patching strategies.

Finding the Right Balance

Each patching strategy has different benefits and limitations. You will need to choose a combination of strategies that provides an appropriate balance between file size and logistical simplicity.

Since a lot depends on how many versions you need to support, and what methods you use to distribute your patches, there is no single "right way" to handle everything. The frequency of your updates is another factor that can determine how "up to date" your users are. For instance, if you release new versions often, and you don’t use an automatic updating technology like Indigo Rose’s TrueUpdate, the chances are higher that several of your users will be more than one version behind.

You will probably want to use a combination of incremental and multi-version patching in order to get the benefits of both. One strategy that works well is to use two separate patches:

· An incremental patch to go from the previous version to the current version

· A multi-version patch for all of the other versions

The assumption is that if most of your users always stay up to date, you will save a lot of bandwidth by providing the incremental patch. This is especially true if you use technology like TrueUpdate to keep your users up to date automatically.

Even if your patch distribution isn’t automated-for example, if the users just click on a download link and run the patch themselves-this approach provides a good balance between minimizing patch size and making things less complicated for the user (by giving them fewer patches to choose from).

If you are using a tool like TrueUpdate, you might want to provide even more patch files, and let TrueUpdate decide which one to download and run.

For example, if you’re about to release version 1.29 of your software, and you know that most of your users are using 1.28 and 1.27, it would make sense to create two incremental patches: one for the users of 1.28 and one for the users of 1.27.

You might also want to create a few different multi-version patches, for example one for versions 1.20 through 1.26, and another for the really old versions 1.0 to 1.19.

Ultimately, the patching strategy you choose depends on the number and sizes of files you need to update. The key point is to consider which method makes the most sense for you, given the distribution methods available to you, and how comfortable your users are with the patching process.

Versions

A version is the collection of files and folders that makes up a single release of your software.

If your original release is version 1.0, then all of the files in that release-everything that gets installed onto the user’s system-constitutes one version.

Each time you modify your software and release it to the public, you create a new version. For example, if your next release is version 1.1, all of the files in that release constitute another version.

Note that a version isn’t just the files that have changed from one release to the next. Each version contains all of the files in your software from a specific point in time. It even includes all of the files that remain the same.

In essence, a version is a complete copy of your software from a specific point in its life cycle.

Version Tabs

Each version is represented in Visual Patch by a version tab on the project window. The version tabs are listed in increasing order, with the oldest supported version on the left and the newest supported version on the right.

Your project should have one version tab for every version of your software that you want to build patches for. Whenever you build the project, you will be able to select which of these versions you want that particular patch to support.

Each version tab contains a file list where you can add the files that belong to that version. Adding a new version to a project involves adding a new version tab, and then adding all of the files from that version into that tab’s file list.

You should put all of the files from each version onto a separate version tab. So for example if you have version 1.1 and version 1.2, put all the files from 1.1 onto a "1.1" tab, and put all the files from version 1.2 onto a "1.2" tab.

Note: Make sure you don’t have any "empty" tabs, or Visual Patch will report an error when you build your project.

For more information on version tabs, see chapter 4, Versions and Files.

Version Management

Since each version tab needs to reference the files that belong to that version, you need to keep a copy of each release of your software.

Each version of your software should be stored in a separate location on your system. A good way to organize your versions is to keep them in separate folders, with each folder named according to the version it contains. Each folder should contain a complete copy of your software, with all internal subfolders intact.

Visual Patch uses delta compression to create amazingly small patch files. This binary differencing engine needs to analyze the entire contents of each file in each version in order to build a binary patch that contains only the data that has changed from one version to another.

The Installed Version

The version that the patch application detects on the user’s system is known as the installed version. It’s the version of the software that was installed by the original software installer.

For example, if the user has version 5.8 of your software installed on their system, and the patch application successfully locates it, "5.8" is the installed version.

In some cases, there may be more than one version of a software program installed on a user’s system. In these cases, the installed version is the one that the patch application identifies as the version to update. Usually this will be based on some kind of information that was recorded on the system by the installer, for example a "current version" entry in the Registry.

The Target Version

The version that a patch application is designed to update an installed version to is known as the target version.

For example, if you create a patch to update version 5.8 to version 5.9, "5.9" is the target version.

Version Detection

Before a patch can begin updating, it needs to determine whether a compatible version is installed on the user’s system. In other words, the first task that the patch must perform is to locate and identify the installed version of your software.

The location where your software is installed is referred to as the application folder.

The Application Folder (%AppFolder%)

The application folder is the folder where your software is installed on the user’s system. Finding the application folder is very important-without it, the patch has nothing to update.

In Visual Patch, the search for the application folder is implemented using actions in the project’s On Startup event. When you use the project wizard to start a new project, it automatically configures the On Startup script to handle this for you.

In screens and actions throughout the project, the application folder is represented by a session variable named %AppFolder%. Storing the application folder path in this session variable is the ultimate goal of any version detection method.

In the default action scripts, this is handled by the VisualPatch.CheckFolderVersion action. This action inspects the folder to determine whether it contains all of the key files for a compatible version.

If the folder meets all of the requirements and is recognized as a compatible version, the VisualPatch.CheckFolderVersion action stores the folder path into the %AppFolder% session variable.

Tip: For more information on session variables, see chapter 7.

Detection Methods

In addition to any "custom" methods you might implement, there are three standard detection methods that are used in Visual Patch. Each of these will be implemented for you by the project wizard in the form of an action script in the On Startup event.

By default these detection methods are designed to follow a specific sequence. Assuming all three methods are enabled, the sequence is to check the current folder, check a specific Registry key, and then perform a file search on the user’s system.

Current Folder

The current folder method checks the folder that the patch is running in to see if it contains a recognizable version of the software. This is done by checking for specific key files in the folder.

This method is useful when your software is installed in more than one location on the user’s system, and the user wants to control which instance of the software is patched. Since the current folder check is performed before the other detection methods, it allows the user to override the other two detection methods by copying the patch file into the folder where the installation they want to patch is installed.

If the current folder doesn’t contain a recognizable version, the patch moves on to the next detection method.

Registry Key

The Registry key detection method attempts to retrieve the application folder path from a specific Registry key. This is the recommended detection method, since it is the fastest and most reliable way to locate the application folder.

In order to use this method, your software’s installer needs to have written the application folder path into a Registry key so that it can be retrieved by the patch.

If an application path is found in the specified Registry key, the patch will verify that it points to a valid version of your software. As in the current folder method, it does this by confirming the MD5 signatures of specific key files in the folder.

If no path is found, or if the key files don’t match, the patch will proceed with the next detection method (assuming it is enabled).

File Search

The file search method searches the user’s system for a folder that contains a version of your software, by checking every folder for the existence of key files. The search ends when it finds a folder that contains all of the key files for a compatible version and the MD5 signatures prove that the key files are a perfect match.

Custom Actions

Since it’s ultimately all done with actions, it’s possible to use a completely different method to determine the folder where your application is installed. In fact, you could even write a script that just set %AppFolder% to a hard-coded path if you were absolutely certain that your software was installed at the exact same place on every system, and was never modified or installed incorrectly.

In the vast majority of cases, though, you will want to use the standard methods described above.

Key Files

Each version of your software usually includes one or more files that are unique to that version. For instance, as new features are added, your software’s main executable might change, along with a help file and perhaps a few data files. Visual Patch refers to these "identifiable" files as key files.

Key files are used to locate and identify your software on the user’s system.

Designating a file as a key file means that you want Visual Patch to verify its existence and its MD5 signature in order to fully identify the version it belongs to. If the key file doesn’t exist, or its MD5 signature doesn’t match, Visual Patch will consider that version not found.

Each release of your software must have at least one key file, but you can specify as many as you want. It’s important to remember that every key file in a version must be found in order for that version to be identified. In other words, a user must have all of the key files from a given release installed in order for their version to "qualify." If you have four key files for a particular version and only three of them are found, the version on the user’s system won’t be considered legitimate. The same goes for a user with three key files from one version, and one from another. All the key files must match the original files from a single release absolutely.

It’s also important to remember that each key file will be verified by its MD5 signature. Care should be taken to avoid selecting key files that are likely to change for legitimate reasons once they’re installed. For example, if your software uses a database file that is constantly updated, that file wouldn’t be a good choice for a key file because its MD5 signature will change. The key files on a user’s system must all be present, and their MD5 signatures must all match the original values determined for those files at design time.

If the patch doesn’t find a valid release anywhere on the user’s system, the user won’t be allowed to update their software.

Choosing Appropriate Key Files

Key files are usually files whose contents are unique to a single version. Visual Patch requires at least one unique key file per version in order to uniquely identify that version. The file names and paths don’t need to be unique, but their contents do. In other words, you must designate at least one key file per version whose contents are different from every other version. Otherwise, the patch won’t be able to tell that version apart from the others.

Key files must also not change after being installed or patched because Visual Patch relies on their MD5 signature for validation. Files that are normally modified after they are installed (for example, .ini files) should never be designated as key files. If a key file has been changed in any way from the original file that is referenced in your project, it will prevent the version from being identified.

Each version can contain as many key files as you like. In fact, it’s a good idea to designate additional key files to help ensure a positive identification.

Tip: Good candidates for key files are executables, images, help files, PDF docs, readme files...anything that can be used to tell one release from another, but isn’t expected to change once it’s installed.

The best key files are files that change from one version to the next, such as the main executable for the software. As a matter of fact, having a main .exe file that is different from one version to another is the perfect example of a key file. It’s a file that must exist (if the .exe isn’t there, the software isn’t properly installed). It’s also usually different from one version to the next, even if all that changes is the version number or the text on the "Help > About" window.

Mission-Critical Files

Although at least one of the key files in a version needs to be unique to that version, they don’t all have to be. You can also use the key file feature to perform validation on mission-critical files. For example, if your software contains a really important file whose existence and integrity must be checked, making it a key file will prevent the patch from proceeding if the file has been removed or modified.

Remember: a version will be identified only if all of its key files are there and they match the originals exactly.

MD5 Fingerprinting

Visual Patch calculates the MD5 fingerprint of each file in order to identify files that are the same and in order to detect whether two versions of a file are different.

The MD5 algorithm is a standard algorithm that is widely used to generate cryptographic signatures. It was developed by Professor Ronald L. Rivest of MIT.
To quote RFC 1321, which describes the MD5 standard:

[The MD5 algorithm] takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input. It is conjectured that it is computationally infeasible to produce two messages having the same message digest, or to produce any message having a given prespecified target message digest.

An MD5 fingerprint is essentially a large number that is calculated directly from the entire contents of a file. If even a single byte within the file changes, the MD5 signature changes as well. For all practical purposes, no two files can have the same MD5 fingerprint unless their internal data matches exactly.

Unrecognized Files

Once the patch application has detected a valid version, it will update each file in the release on an individual basis. By default, Visual Patch will only update files that it recognizes. If a file that is part of the installed version doesn’t match the original source file in your project, it will not be updated. Visual Patch will skip over the unrecognized file and continue with the rest of the patching process.

This behavior is both a security feature and a requirement:

· If whole-file patching is being used, preventing the file from being installed unless the user has a recognizably valid version is a security feature.

· If binary patching is being used, it is impossible to update the file unless its contents exactly match the original file.

You can override this behavior for individual files by enabling the "Force install" option in your project.

Version Numbering

The whole point of Visual Patch is to make it easier for you and your users to update your software. One part of this process is deciding on the version numbering scheme you will use to identify each release of your software.

Visual Patch allows you complete freedom in naming your versions. (You could call one version "George" and the next version "Henry" if you wanted to.) We recommend using an industry-standard version numbering scheme that will be more readily understood by your users. Whatever you decide on, here are some guidelines you might want to consider.

Give each release a number

Using numbers makes it easy for your users to identify the hierarchy between different versions of your software. If you name one version 1.0.3.2 and the next version 1.0.3.3, it’s readily apparent which version is the newer one.

Make the numbers mean something

Version numbering schemes like "version.revision.sub-revision" are popular because they allow you to make the magnitude of an update readily apparent in the version number itself. Going from 1.5.2 to 1.5.3 normally indicates a small change, like a bug fix. Going from 1.5.3 to 1.6.0 would indicate moderate changes, such as new features being added, or improvements to the program code. Going from 1.6.0 to 2.0.0 would be reserved for sweeping changes, like complete rewrites or a completely new interface design.

Aim for clarity

Try to avoid version numbers that might confuse your users. A prime example is a number like 1.10. Is this version newer or older than 1.9? That depends on the numbering scheme being used. The standard "version.revision" scheme makes 1.10 newer than 1.9, since it marks "the tenth revision of the first version" of the product. But many users mistake the version number for a fraction. Even more savvy users that are aware of the "version.revision" standard might wonder if you were as savvy as they are-enough software has been released using fractional notation to make it a difficult guess. One solution is to use double digits for each part, so that 1.9 becomes 1.09 and the ordering becomes readily apparent.

Don’t rely on file sizes or date stamps

Make it a habit to issue a new version number whenever you release a new version of your software. Don’t expect your users to identify versions based on changes in the file size or date stamp alone. Not all users will be able to determine this information easily, and date stamps may be subject to change as files are downloaded or copied.

Simpler is better (within reason)

Avoid using a numbering scheme that involves long awkward version names like "49823.B345.14231-A." At the same time, avoid overly simple schemes that might limit your ability to release updates often.

Don’t go overboard

Your external version numbers don’t need to reflect the number of compilations your software has been through since the last version. They also don’t need to reflect how many failed attempts there were before a new feature started working. The version numbers your users see should only reflect the changes that are visible to them. Keep external version numbers "tight" between consecutive releases. (Releasing version 2.0.29 right after version 2.0.21 could have your users searching for nonexistent versions like 2.0.28 if they run into any problems with 2.0.29. If you must track recompilations internally, consider keeping your internal version numbers separate from the version numbers that your users will see.)

Be consistent

If your numbering scheme is "MajorUpdate.MinorUpdate.BugFix," don’t start incrementing your "major update" number when you’ve only put out a bug fix.

Avoid unnecessary changes

Once you decide on a numbering scheme, stick to it. Switching from one scheme to another could be confusing for your users, especially if the new version numbers look similar to the old ones. If you really must switch, make sure you take steps to explain the changes to your users.

Tell your users what has changed

It’s always good to tell your users what new features or bug fixes a new version brings. A rich and detailed version history makes a good impression on your users, because it shows how much time and effort you’ve spent improving your product.


Chapter 2: The Project Wizard

User's Guide - Chapter 2: The Project Wizard

The Project Wizard

Every journey begins with a first step. In Visual Patch, this first step is easily accomplished through the Project Wizard. In this chapter we will walk you through opening Visual Patch for the first time and creating a project using the Project Wizard.

Starting a New Project

Everything has to start somewhere. In Visual Patch, 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 a patch. A typical project will contain all of the files that you want to patch, 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 patched version number in a registry key for future patches to use).

The project file

Each file that you add to a Visual Patch project has individual settings that control where, when and how the file will be included in the patch at build 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 at run time.

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, Visual Patch’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.

Let’s open the Visual Patch program and start a new project.

1) Open Visual Patch

Use the Start menu to launch the Visual Patch program.

By default, you’ll find Visual Patch under:

Start > Programs > Indigo Rose Corporation > Visual Patch 3.0

2) Create a New Project

The Welcome dialog appears whenever you run Visual Patch. It not only welcomes you to the program, it also lets you easily create a new project, open an existing one, or restore the last project you worked on. (Restoring the last project automatically opens the project you were working on the last time you ran Visual Patch.)

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

3) Enter General Project Information

First, the project wizard asks you for three pieces of information related to your project. Simply enter your company name, product name, and your company URL in 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 all of the default project settings untouched (i.e. to start with a "blank" project).

4) Choose an Interface Type

The next step in the project wizard is to specify which type of user interface your patch executable will use.

The most common patch user interface is the default Wizard style. A Wizard style interface presents the user with a series of screens that they can navigate through by clicking Next and Back buttons. Wizard interfaces are considered very user friendly because they present and request information in discrete, guided steps, which makes the overall process easier for the user to understand.

The other two interface styles are Dialog and Silent. A dialog user interface uses popup dialogs or "message boxes" as opposed to screens to guide the user through the patch. A silent patch runs entirely in the background, and has no user interaction whatsoever. It’s a great choice for unattended or automatic patching preferred by network administrators.

5) Pick a Window Style

This step determines whether or not your patch will have a background window covering the user’s desktop.

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

If you select the background window style, you can specify how you want the background window to look. It can display a solid color throughout, a top-bottom gradient, or an image of your choosing.

6) Select a Project Theme

This step allows you to pick a visual theme for your wizard-style patch. Each theme applies a different overall appearance to the patch.

Once you’ve selected your project theme, click Next to proceed to the next step.

7) Define Versions

Use this step to add versions to your patch. Clicking on the Add button allows you to add a version to your patch. To make adding versions to your patch as easy as possible, store each version of your software in a separate folder on your development system. Then, using this step, add those folders one by one. For each version added, you can opt to add the folder recursively, which means that all files from that point downward in the directory structure will be added.

Once you have added a folder, you must specify a key file. This is the file that Visual Patch will use to determine if your software exists on the user’s system, and what version is already installed. It is important to select a file that is version specific, such as your program’s executable, or a DLL.

Note: You can skip this step and add versions after the wizard is completed. You can also make changes to these versions, or delete them entirely in the design environment. For more information on key files, see Chapter 1.

Once you have added all of your product’s versions to the wizard, click Next to continue.

8) Decide How to Locate your Installed Software

Visual Patch must be able to find your existing files on the user’s system in order to patch them. There are a number of ways that Visual Patch can do this. Your patch executable can: search for the files in the location from which it was run, retrieve a value from the registry, and search either specific folders or entire drives on the user’s system.

Enabling the Current folder option creates a "failsafe" patching method: if the user has your software installed, but the patch can’t find it, you can direct them to copy the patch to the install location and run it. This option by itself, however, is not sufficient as many users have no idea where your software is installed.

Retrieving a value from the system Registry is by far the best locating method, though it does require some forethought on your part. In order to use this method, your software installer must create a registry value during installation. Then, it is a simple matter of configuring Visual Patch to inspect that registry key so the value can be retrieved. This is the most efficient method as accessing a single registry key is quick and not resource intensive.

If neither of the previous methods has located your software, a file search can be performed. This option scans the entire system looking for your software. It is a rather intensive and lengthy operation, but is an excellent choice of last resort.

9) Locate Using Registry Key

Visual Patch can retrieve your software’s installation folder from a specific registry key. Use this step to specify the location in the Registry that contains the path where your software was installed.

10) Locate Using File Search

Visual Patch can search all or part of a user’s system for key files. Use this step to configure specific locations to search, as well as whether or not entire local and networked drives should be searched if key files are not located in the specified folders.

This option searches the user’s system for a file known to exist in your product. If found, the software’s version number is determined from key files located within the found file’s path (a VisualPatch.CheckFolderVersion action is used).

Note: Searching a user’s system for a file can be resource intensive, especially if searching entire drives. This should occur only as a last resort. Retrieving a value from a registry key is much more efficient.

11) Select Optional Features

There are several optional features that are useful, though not required. Creating a log file while patching is an excellent tool for diagnosing potential errors that may arise. Additionally, warning the user if they do not have Administrative privileges is an excellent way to prevent patching problems resulting from the user not having the correct permissions.

In addition, requiring that the user closes your application before the patch will continue is an excellent way to minimize ‘locked file’ issues.

Enabling the Backup patched files option creates a backup copy of any file modified during the patching process. Enabling rollback support allows files modified to be ‘rolled back’ to their unmodified versions should an error occur while patching or if the user aborts the patching process.

12) Click Finish to Create your Patch

After you click Finish, the project wizard will close and the design environment will appear, complete with scripts, screens, and folder structures configured with the settings you chose in the project wizard.

At this point, you could build the project and generate a basic patch 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 5.

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


Chapter 3: The Development Environment

User's Guide - Chapter 3: The Development Environment

The Development Environment

This chapter will take you on a tour of Visual Patch’s development environment. You’ll learn how to use the features of the interface that allow you to create a comfortable and productive work environment, customized for the way you want to use the program. You’ll also learn how to take advantage of Visual Patch’s self-help resources, which are designed to answer any questions you might have while working with Visual Patch as quickly and efficiently as possible.

The Visual Patch Program Window

Now that you have started visual patch and created a new project, either through the Project Wizard or from scratch, it’s time to get comfortable with the program interface itself.

The Visual Patch 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.

Most of the program window is taken up by the file list, which is where all the files in your project are listed. There is one tabbed list for each version of your software.

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. As well, 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 when it was pinned.

Tip: When you’re dragging panes, it’s 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 pane’s title bar.

Toolbars

Toolbars in Visual Patch provide quick access to many of the more commonly used features. There are four toolbars available – Standard, Versions, Common, Filters – with the first three displayed by default.

Showing & Hiding

All four toolbars can be shown or hidden in the design environment. To show or hide a toolbar, simply right click on any toolbar, and click on the one you wish to change.

Customizing

If the default toolbar configurations are not fulfilling your needs, you can customize them. To customize the toolbars, right click on any toolbar and choose ‘customize’. Doing this opens the Customize dialog, where you can show or hide existing toolbars, create new toolbars, add or remove individual toolbar buttons, create keyboard shortcuts, change the toolbar themes, and adjust various other options.

Task Pane

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

Version Tabs

In Visual Patch, your application’s various versions are represented by version tabs on the project window. In a nutshell, every version of your software loaded into your Visual Patch project will have its own version tab.

Note: For more information about versions, files, and other related concepts see Chapter 1 and Chapter 4.

File Lists

Each version tab is linked to a separate file list. File lists contain all of the files and folder references associated with that particular version of your software, and provide you with a central location to manage its contents.

From this file list, you can change the properties of one or many files or folder references; you can change the source folders, destination folders, whether or not certain files are key files, and under what condition a file will be patched.

Columns

The file list is divided into many columns, allowing you to quickly locate relevant information. You can decide which columns are displayed by selecting View > Columns. From the same dialog, you can change their display order.

You can use the displayed columns to sort your file list; by clicking on a column header, you can sort your entire file list by the information contained in that column. For example, by clicking on the filename column, all files and folder references will be sorted by their filename.

Filters Toolbar

The filters toolbar allows you to apply both default and custom filters to the file list. Filters display files in the file list matching certain criteria, and hide those that don’t. By default Visual Patch is configured with three filters: All executables, all key files, and all missing files. You can create custom filters based on any available column in Visual Patch. Note that the column used in the filter does not need to be visible in the design environment, and that only one filter can be applied at a time.

Right-Click Context Menus

A quick way to change many settings within your Visual Patch project is to use the various right-click context menus available. For example, right clicking on a version tab will allow you to add a version, remove the selected version, rename the selected version, or organize all available versions. Right clicking on the file list brings up various options for working with existing files in the list, and allows you to add new files and folder references to your project.

Setting Preferences

There are a number of preferences that you can configure to adjust the Visual Patch design environment. To access the Preferences dialog, choose Edit > Preferences from the file menu.

The preferences are arranged into categories 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.

The first category contains the build preferences. Here you can specify whether or not the publish wizard should be used, as well as how Visual Patch behaves before and after the build. You can also specify where the log files should be saved to, or even disable the log files.

The Document preferences allow you to change settings that affect the project file. For example, you can configure the auto-save feature that automatically saves 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 whether 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.

The Environment category allows you to customize the design environment, and the Environment > Folders category allows you to specify the locations of various folders that are used by the project.

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 > Adding Files category). Take some time to look through the categories and familiarize yourself with the different options that are available.

Updating Visual Patch

As with any application, Visual Patch 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 Visual Patch installed, you can check for updates by choosing Help > Check for Update from the program menu.

Note: Visual Patch 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 (Help > Preferences).

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

Getting Help

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

F1 Help

The online help is only a key press away! Visual Patch comes with an extensive online program reference with information on every 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 > Visual Patch Help.

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

User Forums

Visual Patch is used by developers all over the world. 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 website.

Technical Support

Choosing Help > Technical Support allows you to either check out the various support options available to you or to contact Indigo Rose’s technical support department.

Choosing Support Options takes you to the Visual Patch web site, where a variety of online technical support resources are available to you, including a knowledge base with answers to common questions. This is also where you can find information about ordering one of our premium support packages and submitting a support request.

Choosing Contact Support takes you directly to the support ticket submission web page within Visual Patch’s support website.


Chapter 4: Versions and Files

User's Guide - Chapter 4: Versions and Files

Versions and Files

A version is the collection of files and folders that makes up a single release of your software. Having accurate information about your versions and the files they contain is a crucial part of performing a successful patch.

Visual Patch uses this information to analyze the differences between your versions, to determine what data needs to be included in the patch, to identify which version (if any) is actually installed on the user’s system, and to update the files in the installed version so they match the files in your target version.

Since the entire patching process depends on the information you provide, it’s important to understand how to configure all of the versions and files in your project.
This chapter will explain everything you need to know about versions and files in order to create a successful patch for your software.

Note: Patching files is the ultimate purpose of any software patching tool. As such, you are expected to be completely familiar with files and folder structures in order to use Visual Patch. If you need more information on the basics of files and hierarchical folder structures, please consult the "Windows Basics" section of the Visual Patch help file.

The Project Window

The project window contains a series of version tabs, each containing the lists of files that are part of each version. From these lists you can highlight specific files and view or edit their properties.

Version Tabs

The version tabs on the project window represent each version of your software. New versions may be required to fix bugs or to introduce new features. Every version of your software that your patch will update must have a separate file list that contains all of the files that are part of that particular version. Version tabs are organized from left to right where the leftmost version tab is the oldest version and the rightmost tab is the newest version. These tabs allow you to switch between the versions in your project to view or edit their file lists.

Adding Versions

Each time a new release of your software is created, you will need to add a new version tab to your project so you can add all of the new version’s files. The following steps can be taken to add a new version to your project:

1. Select Versions > Add from the program menu.

Selecting Versions > Add from the program menu opens the New Version dialog where you can specify the name you want to give the new version.

2. Specify the name of the new version.

Version numbers are normally used as the version names, but you are not limited to version numbers. You could also use a word or phrase.

Tip: If you use version numbers, whenever you add a new tab Visual Patch will automatically try to guess the next version number based on the previous versions in the project.

3. Click the OK button to create the new version.

When you click the OK button, a new version tab with the specified name will be added to the right of all existing version tabs.

Removing Versions

Occasionally mistakes are made that require the removal of a version from your project. To remove a version, select the version you want to remove and then choose Versions > Remove from the program menu. A confirmation dialog will be shown before the version and its referenced files are removed from your project.

Renaming and Duplicating Versions

Versions can be renamed in your project by choosing Versions > Rename from the program menu. This will open the Rename Version dialog where you can specify its new name.

It is also possible to duplicate a version and all of its file references in your project. To do this, simply select the version you want to make a copy of, and choose Versions > Duplicate from the program menu. This will add a new version tab with an automatically generated name containing the same file list as the copied version. After the version duplication, you may want to rename the new version to suit your project.

Organizing Versions

The order of the version tabs in your project is very important. Positioning your versions in the wrong order would result in a patch that is unable to update your software. In order to build a patch that can successfully deal with all your software versions, you need to ensure that Visual Patch "sees" the versions in the correct order, from the oldest on the left, to the newest on the right.

When you build a patch, Visual Patch analyzes the files in the newest version of your software and compares them to the files in all the other versions that are defined in the project. It uses this information to determine what changes are required to update each version to the newest.

If the order of your versions is incorrect, the following steps can be taken to reorganize them to match your software’s version history:

1. Select Versions > Organize from the program menu.

The organization of the version tabs in your project can be changed on the Organize Versions dialog. You can access this dialog by choosing Versions > Organize from the program menu.

The Organize Versions dialog shows a list of all the versions that are currently in your project and orders them top down, from oldest to newest.

2. Select the name of the version whose order needs to change, and click the Move Down button.

On the Organize Versions dialog shown in step 1, you will notice that version 1.0.0.2 is in the second position while version 1.0.0.1 is in the last position. This order indicates that 1.0.0.1 is the newest version. Lets assume that this is incorrect and that 1.0.0.2 is the newest version of the software. This means that version 1.0.0.2 needs to be moved into the last position in the list.

To move version 1.0.0.2, you would first select it in the list, and then click the Move Down button (the one with the arrow pointing down).

3. Confirm the positions of all versions, and click OK.

Repeat step 2 until all the versions are in the correct order. Once you’re satisfied with the order of the versions, click OK to make the changes to your project. The version tabs in your project should now follow the order you specified on the Organize Versions dialog. For example, if you moved version 1.0.0.2 to the bottom of the list, version 1.0.0.2 would now be the rightmost version tab.

File Lists

Version tabs in Visual Patch were designed to contain the lists of files that are part of each version of your software. Since a minimum of two versions is required to create a patch, your project will normally contain at least two lists of files. These lists contain references to each file on your local system or LAN where Visual Patch can access them during the build process. These lists should only contain the files that are distributed to the user.

The best strategy for managing your source files is to keep each version of your software in a separate folder. It is also best to preserve the internal folder structure for each version, i.e. to store each version complete with any subfolders relative to the main application’s folder. This greatly simplifies the process of adding the versions’ files to your project and setting their destination paths.

File lists can also be sorted and filtered so you can easily find or focus on the files you need to customize. Each file within a list has properties you can view or set such as its source and destination paths, key file property, and patch conditions.

Column Headings

All 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 heading for that column. If you click on the same heading 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 file 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 Visual Patch 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, Visual Patch won’t be able to build it into the patch 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

If your software contains many files, you might find it easier to temporarily "hide" some of them from the file list in order to focus on the files that you’re interested in at the moment. You can do this by applying 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 are currently missing from your system. This is all done using the Filters toolbar.

Clicking the 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.

The filters are saved on a global basis, so once a filter is defined it can be used in all of your projects. You can switch between filters by using the drop-down selector on the filters toolbar.

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 documents that you need to patch, 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 .doc files and all other files in your product’s 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\ProductX that matches "*.doc" and another one to add everything in that same path that are "Files that do not match" the "*.doc" file mask. You could then configure their settings differently-for example, you could set one up with a condition so it only patches the .doc files on specific operating systems.

Tip: Folder references are one of the most powerful features in Visual Patch! 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. Visual Patch 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.

Adding Files

One method for keeping source files organized is to keep each version’s source files in a separate folder. While this strategy may take up additional hard drive space, it greatly simplifies the management of your patches.

Once you have added a new version tab to your project, the next step is to add all of its source files.

1. Click on one of the version tabs.

Select the version tab whose source files you want to add to the project.

2. Choose Versions > Add Files from the program 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.

At the bottom of the Add Files to Project dialog is a section labeled "Add Mode." This setting controls which files in the folder structure will be added to the version’s file list. There are three add modes to choose from:

· 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 subfolders" option will add all of the files in the current folder, and all of the files in any subfolders as well

4. Select the files that you want to add, or navigate to the folder where all the files (and possibly subfolders) 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.

Tip: You can also add files to your project by dragging and dropping them onto the selected version tab in the project window.

Adding Folder References

If your software contains folders of files whose settings do not need to be individually customized, folder references are a convenient way to add those files to your project.

Assuming you have a version tab ready for files to be added, the following steps can be taken to add a folder reference to your project:

1. Click on one of the version tabs.

Select the version tab whose source files you want to add to the project as a folder reference.

2. Choose Versions > Add Reference from the program 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.

Tip: You can also drag and drop a folder onto the selected version tab to add a folder reference to your project. This will open the Drag and Drop Assistant dialog to confirm its addition.

Removing Files

To remove files from your Visual Patch 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 Edit > Delete.

Choosing Edit > Delete 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 Edit > Delete (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 one of your version tabs.

Simply select the file item that you want to edit.

2. Choose Versions > 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 three tabs on the File Properties dialog: General, Conditions, 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, whether it’s a key file, and where it is expected to be on the user’s system (the destination path).

Filename

The Filename field specifies the name and extension of the file being referenced.

Local folder

The Local folder specifies the current location of the file on your system. This must be a folder that is within local access of your system or LAN.

Visual Patch uses the local folder in combination with the filename to retrieve the file’s information (e.g. when you open a project) and to analyze the file when it builds the patch executable (i.e. when you build the project).

Key file

Key files are a very important part of Visual Patch. Key files are used to identify what version of the software is on the user’s system and whether or not it is a valid version. Designating a file as a key file means that you want Visual Patch to verify its existence and its MD5 signature in order to fully identify the version it belongs to. If the key file doesn’t exist, or its MD5 signature doesn’t match, Visual Patch will consider that version not found.

Key files are usually files whose contents are unique to a single version. The best key files are files that change from one version to the next, such as the main executable for the software. The file names and paths don’t need to be unique, but the contents do.

Visual Patch requires at least one unique key file per version in order to uniquely identify that version. In other words, you must designate at least one key file per version whose contents are different in every other version.

Key files must also not change after being installed or patched since Visual Patch relies on their MD5 signature for validation. Files that are normally changed after they are installed (for example, .ini files) should not be designated as key files. If a key file has been changed in any way from the original file that is referenced in your project, it will prevent the version from being identified.

A version can contain as many key files as you like; however, only one key file must be unique between versions. If your software contains mission critical files whose existence and integrity must be checked, you can set them as key files as well, even though they haven’t changed between versions. Again, only one unique key file is required to identify a version.

Install to

The Install to (or "destination") property specifies where the file is expected to exist 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 patch a file located 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."

Visual Patch 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 Visual Patch will take care of investigating what the actual path is when your user runs the patch file.

For more information on session variables, see Chapter 7.

%AppFolder%

In most cases you know the directory structure of your software, however the user is often given the choice of where they would like to install. For this reason, the exact folder path is not known until run time. Visual Patch uses a special session variable to represent the main folder that your software was installed to. The name of this session variable is %AppFolder%, which is short for Application Folder, i.e. the folder where your software application is installed. At run time, this variable is populated with the folder path from a Registry value, file search, or some other method implemented using action script. (By default, the setting of %AppFolder% is handled in the On Startup event by the VisualPatch.CheckFolderVersion action.)

Force Install

The Force install check box is for files that you always want installed as part of the patching process for a given version. It instructs Visual Patch to include the whole file in the patch and to overwrite any existing version of the file that it finds on the user’s system.

You should only enable this option when you’re sure that it’s okay for a file to have been modified after it was installed, and you want to overwrite the modified version with the new file. (Generally you will want to leave this option unchecked.)

Conditions

The Conditions tab is where you can edit settings that affect whether the file will be included in the patch executable, and whether it will actually be used when the patch is run. In other words, it is used to conditionally include or exclude a file from the patch 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 patch if it is included in the build configuration that is selected when you build the project.

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

The script condition is a short expression written in Lua script. 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 patched. For example, if you have a variable used in your project called MyNum and you want to check to see if its value is 5, the script condition would be MyNum == 5. If the contents of the variable is 5, the condition evaluates to true and the file will be patched. If the variable contains some other value, the condition evaluates to false, and the file will not be patched.

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 patch, and are not included in the patch executable. 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 the same properties as files do. In fact, the Conditions and Notes tabs are exactly the same. However, there are a couple differences on the General tab worth mentioning:

Folder references have a "Recurse subfolders" option that controls whether files in subfolders (and their subfolders) should be included as well. This allows you to include full folder trees if you wish.

Folder references also have a File mask setting that allows you to include or exclude a range of files that match a filename pattern, e.g. "*.exe". This allows you to use custom settings for different file types.

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 a version tab. (You can select multiple files by pressing and holding the Ctrl key or the Shift key while you click on the files.)

2. Choose Versions > 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 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, disabled, and mixed. The mixed state preserves the settings for that check box in all of the selected files.

For more information on using the Multiple File Properties dialog, please consult the Visual Patch help file.

Missing Files

Since Visual Patch 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 Visual Patch’s point of view. For example, if a file in your project has moved to another folder, Visual Patch will no longer be able to find it at its original location. The same thing happens when a file is renamed or deleted. Visual Patch only knows to look for a file at the place where it was when you "showed" the file to Visual Patch by adding it to your project.

Although Visual Patch 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, Visual Patch displays the file’s information 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, if that column is enabled. You can enable the Status column from the column settings dialog found by choosing View > Columns from the program menu.

Tip: A quick way to determine which files are missing in your project is to click on the Status column heading 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 Visual Patch, 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 Visual Patch 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 program menu, or press the F5 key. Refreshing the display causes Visual Patch to re-examine the location of every file in your project.

Note: Visual Patch 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 Visual Patch 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 get extracted from the patch executable before the patch process begins. This means you can use primer files at the very start of the patch process, right after the user runs the patch executable. Primer files are useful in situations where changes need to be made before the normal patching process begins.

One use of primer files is to run a program on the user’s system before the rest of your files are patched. For example, you might need to execute a custom program or DLL function before your software is patched-perhaps to perform some product-specific, low-level pre-patch 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 patch executable and still be able to run it before any of the "normal" files in your project are patched.

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

Any type of file can be added as a primer file simply by adding it to the Primer Files tab on the Resources dialog. All files on this tab will be included in the patch executable when you build your patch, but are not part of any version of your software.

Tip: Another way to access files at the start of the patch is to distribute them "alongside" your patch. 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 5: Creating the User Interface

User's Guide - Chapter 5: Creating the User Interface

Creating the User Interface

Creating the user interface is an integral part of every project since the user interface is the first thing your end users will see when they run your patch. It also serves as a bridge between the information that the user has and that the patch wants. Having an easy to use yet fully functional user interface is something that all developers working with Visual Patch 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.

The User Interface

You can think of the user interface as any part of the patch process 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:

· Screens

· Themes

· The Background Window

· Taskbar visibility

· Any actions that generate a user interface element (e.g. Dialog.Message, StatusDlg.Show)

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 patch. Screens allow you to provide important information, such as whether or not a valid software version was located.

Screens are the individual windows that make up your patch. When you navigate through a patch by clicking the Next and Back buttons, you are navigating from screen to screen, exactly as you would navigate through any wizard.

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

The Screen Manager

The screen manager is where you will configure all of your screens. In Visual Patch, the screens are divided into three stages.

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

· Before Patching

· Progress

· After Patching

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

Before Patching

The Before Patching screens are displayed before the actual patching of any files occurs. In general, if the end user cancels the patch during this stage, no files will be patched on their computer.

This stage is used to perform such tasks as letting the user know what version his or her software is being patched to, displaying a license agreement, and collecting user information.

Progress

The Progress screen stage is displayed while the files on the end user’s computer are being patched. This stage differs from both the Before Patching and After Patching 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 patching progress as it occurs. In other words, while the user’s files are being patched, the screen you chose for the Progress stage will display information about the progress of the patch, such as what file is being patched, what percentage of all files have been patched thus far, and what percentage of the current file has been patched.

After Patching

The After Patching stage is the final screen stage and occurs after all of the files have been patched on the end user’s computer.

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

Adding Screens

Adding a screen to your patch is easy. Select the stage where you want to add the screen, and click the Add button at the bottom of the screen manager.

Note: The Progress 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. Select the type of screen you want and 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 patch, simply select it in the screen list and click the Remove button.

Tip: If you remove a screen from your patch by accident, you can undo the deletion by pressing Ctrl + Z, or by pressing the Cancel button.

Organizing 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, select a screen in the list and click the Up or Down button until it’s 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 screen’s properties, 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 Visual Patch help file.

Attributes

The Attributes tab contains settings that are common to all screens. The only difference that you will find between Attributes tabs is 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 screen’s events. For more information on actions please see Chapter 6.

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 patches.

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

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 Visual Patch that looks like %ProductName%, you are looking at 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 (e.g. %ProductName%) is replaced at run time by its value (e.g. "Visual Patch"). 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 product name 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, an edit field screen will use session variables to store information that the user has entered.

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 7, which discusses session variables in more detail.

Screen Navigation

Screen navigation can be thought of as the path that the end user takes through the visible part of the patch process. The end user navigates forward through the screens by clicking the Next button, and backward through the screens by clicking the Back button.

The default screen navigation is 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 patch 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 user’s navigation by canceling the patch.

The settings for these buttons can be found on the Attributes tab of the screen properties dialog. 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 user’s 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 patching process. 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.

Each event represents something that can happen while your patch executable 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 patch 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 Visual Patch: Screen.Back, Screen.End, Screen.Jump, Screen.Next, Screen.Previous, and Application.Exit. Of those, the most commonly used are Screen.Next and Screen.Back.

When the Next button is clicked, the user is attempting to navigate from the current screen to the next screen or phase of the patch. 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 user is attempting to move backwards in the patch to the previous screen. To implement this behavior, a Screen.Back action needs to be executed when the On Back event is fired.

Tip: The Screen.Back action moves backward in the patch’s 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 patch-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 patch to stop as soon as it is performed.

Note: For more information on the specifics of screen actions, please see the help file.

Screen Layout

In Visual Patch choosing a layout for your screens and the controls on them is simple. You can switch between all three banner styles (top, side, and none) on any screen that you like. 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 Visual Patch are divided into three basic parts: the header, the body and the footer.

The header runs across the top of each screen and is 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.

The body is any part of the screen that is not taken up by the header or footer- it takes up the majority of each screen and contains most of the screen’s information.

Banner Style

In Visual Patch 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 Visual Patch: none, top, and side.

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

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. Visual Patch 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.

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 just above the screen’s footer. This is the side banner area.

The side banner style supports an image that will automatically be stretched or resized by Visual Patch to fill the entire side banner area.

Dynamic Control Layout

One of the best features of the Visual Patch system is the dynamic control layout ability of screens. Visual Patch 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 add more text. The layout will be automatically chosen based upon your control settings.

For example, you do not have to worry about fitting your descriptive text within two or three lines. If you want a fourth (or fifth) line just type it in, and all of the controls on the screen will adjust to fit the new lines of text.

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 screen’s body area. Its size is controlled by the theme settings.

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 Visual Patch will re-position all the controls so that everything is visible.

Of course, you still have full control over how controls will be displayed on your screen. Many screens (Edit Fields, Checkboxes, etc.) allow you to add as many as 32 controls to your screen, which Visual Patch 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!

The best way to understand the dynamic control layout feature is to use it. Try playing around with the settings of a Check Boxes screen or Select Folder screen and observe how Visual Patch positions your controls to achieve the best look possible.

Themes

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

Themes in Visual Patch 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 patch unless intentionally overridden on the style tab of the screen’s 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.

Choosing a Theme

You can choose a theme for your project on the theme tab of the Project Settings dialog, which you can access by choosing Project > Settings, and clicking on the Theme tab.

The drop-down list on the Theme tab contains a list of all the themes that are available in the project. Selecting a theme in this drop-down list will apply the theme to all of the screens in your project. For your convenience, a preview of the currently selected theme is displayed on the Theme tab as soon as you make a selection.

As shown above, themes affect the appearance of screens and their controls. For example, choosing a theme that colors 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

Visual Patch 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 > Settings, making sure that the theme tab is selected.

The first step in creating a custom theme is to select an existing theme to base your new theme upon. If you cannot find a suitable theme, simply choose the default theme.

Once you have selected a theme to start from, use the Save As button to save a copy of it under a new name. Choose a name that describes the theme you plan to make; this theme is what you will be modifying in order to create your new 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 click 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 Visual Patch 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.

Overriding Themes

As stated earlier, project themes affect every screen in your project. 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, Visual Patch 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 it. If you look at the Style tab you will notice that it looks identical to the Theme tab on the Screen Properties dialog except that it has a checkbox in the top left corner labeled "Override project theme."

Choosing the override project theme option will enable the theme settings and allow you to make changes to the theme settings strictly for the current screen. The changes you make on the Style tab will not affect 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 it, simply go to the Style tab and uncheck the Override project theme checkbox. There is no need to re-create the screen.

The Background Window

The background window is an optional maximized window that can appear behind all screens in your patch. Its main use is to focus the end user’s attention on your patch by blocking out the rest of the desktop.

The background window can be enabled in one of three styles:

· Standard – all the features of a normal application window (i.e., a title bar with a close button and a standard window border).

· Bordered – a standard background window without a title bar or close button.

· Kiosk – a standard background window without a title bar, close button, or border.

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

No matter which of the above styles you choose, you can configure the appearance of the background window through the Background Window tab on the Project Settings dialog (Project > Settings). You can specify what the content of the background window should be (solid color, gradient, or an image), what text will appear on the window, and how the text will look (font, size, and style). You have the option of having a heading, subheading, or footer in any combination, or none at all.

Other Interface Options

There are a few other options in Visual Patch that relate to the user interface of your patch. These options may not be as important as screens or themes, but they just might provide the elements necessary to perfect your project’s 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.

Visual Patch 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 > 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 patch to be a silent patch in the advanced settings then no taskbar entry will appear.

Actions

Some of the actions available to you in Visual Patch 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.

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.

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 Visual Patch help file.


Chapter 6: Actions, Scripts and Plugins

User's Guide - Chapter 6: Actions, Scripts and Plugins

Actions, Scripts and Plugins

Visual Patch comes standard with a plethora of actions allowing you to create more powerful patches than ever before. They are what you use to accomplish the specific tasks that make your patch unique. Each action is a specific command that tells your patch to do something, such as retrieving a value from the Registry.

Actions also allow your patch to react to different situations in different ways. Does the user only 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 patch 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 Visual Patch with virtually limitless possibilities.

What are Actions?

Actions are specialized commands that your patch can perform at runtime. Each action is a short text instruction that tells the patch 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 Visual Patch 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 Visual Patch handles the most common patch 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 patch tasks. Actions let you customize what Visual Patch does for you automatically so that you can meet your patch needs exactly.

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 Visual Patch help file (Help > Visual Patch Help).

Note: In order to try out the example scripts in this chapter, you will need a basic project that you can build so you can run the patch application and see the scripts in action. Please see Chapter 10 for more information.

The Action Editor

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

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 Visual Patch, intellisense manifests itself as two features: autocomplete, and the autocomplete dropdown.

Autocomplete is the editors 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 available 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 actions parameters and indicates what type of value is expected for each one. In the case of our Window.EnumerateTitles action, the quickhelp looks like this:

table Window.EnumerateTitles(boolean TopLevel = true)

The quickhelp above indicates that the action Window.EnumerateTitles takes a single parameter called TopLevel, and that this parameter needs to be a boolean value. It also indicates that Window.EnumerateTitles returns a table value.

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 actions help topic.

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 actions help topic.

Note: The context-sensitive help 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 patch 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 patch.

In Visual Patch there is an action editor for every event. When you add an action in an events 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 patch has four main project events: On Startup, On Pre Patch, On Post Patch, and On Shutdown. These events can be thought of as bookends to the main phases of the patch. The remaining events in Visual Patch are triggered by the screens.

Project Events

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

The four project events are:

· On Startup

· On Pre Patch

· On Post Patch

· On Shutdown

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

The On Pre Patch event is triggered just before the patch enters the patching phase and begins patching files on the users computer. This event is fired right after the last screen in the Before Patching screen stage is displayed.

The On Post Patch event is triggered after the patching phase of the patch has been completed, right before the first screen of the After Patching screen stage is displayed.

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

Screen Events

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 patch folder).

There are two main types of screens in Visual Patch: 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 patch. They can be further broken down into two types of progress screens: those used in the Before Patching and After Patching screen stages, and those used in the Progress stage. In general progress screens used in the Before and After Patching screen stages show progress that arises from actions. Progress screens that are used during the While Patching screen stage are used to show the progress of the main patch 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 patch, 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 Patching 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 Starts 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 Patching screen stage:

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

· On Progress fired as progress is made during the patch 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.

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 patch. 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 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 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 Visual Patch will fill most parameters with defaults.

For now change the title to:

"Visual Patch"

and the text to:

"Message from Chapter 6!"

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

Once you've set the actions parameters, click the Finish button to close the action wizard. The Dialog.Message action will appear in the action editor. It will look like this:

Dialog.Message(Visual Patch, Message from Chapter 6!);

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 and click the Next button. Build your patch 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.

Note: You must have at least 2 version tabs in your project (containing at least one file each) in order to successfully build your project.

Once the folder where you built your patch appears, double-click on your patch executable to launch it. You should see the 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 editor 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 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 actions current parameters.

Tip: You can also edit the actions 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 patch, a dialog will pop up. The dialog is created by the Dialog.Message action on the On Startup event of your patch. Notice that there is no icon and that a cancel button has been added the dialog.

Getting Help on Actions

You can get help on actions in a variety of different ways in Visual Patch. 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 click the blue hyperlink 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 actions function prototype. The help button to the right of the quickhelp will open the Help file directly to that actions 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 Visual Patch 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 Visual Patch. 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. For example, if the action returns a value, 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 Visual Patch 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 Visual Patch where the end of the statement is. It acts as a terminator. (No relation to Arnold, though.) Although technically it's optional and Visual Patch 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 above.

Start a new Visual Patch project by selecting File > New Project from the menu. If you have any unsaved changes in your current project, Visual Patch 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 6! string with a variable named strMsg.

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

Dialog.Message("Visual Patch", 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.

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 patch 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 patch. 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 variables 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 projects On Startup event.

Note: You must have at least 2 version tabs in your project (containing at least one file each) in order to successfully build your project.

5) Exit the patch. 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("Visual Patch", strMsg);

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

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 statements 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 statements 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 projects 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("Visual Patch", 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 patch 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 patch. 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("Visual Patch", strMsg);
end

The tilde equals (~=) compares for inequality (does not equal), so this if statements 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 programmers 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 patch. Edit the projects On Startup script to look like this:

strMsg = Dialog.Input("", "Enter your message:");
if String.Upper(strMsg) == "HELLO WORLD!" then
Dialog.Message("Visual Patch", 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 statements 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 patch. Try typing different messages into the input field by closing and re-running the patch.

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 statements 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.

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, lets create another script that will stop your patch from running after it has been run on the same system more then 5 times.

1) Add the following script to a new projects On Startup event:

nRuns = Application.LoadValue("VPUsersGuide", "Chapter6");
if nRuns == "" then
nRuns = 0;
end

nRuns = nRuns + 1;

Application.SaveValue("VPUsersGuide", "Chapter6", nRuns);

if nRuns>5 then
Dialog.Message("Sorry!", "Patch 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 patch 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 patch.

We used the concatenation operator to join the current value of nRuns to the end of the string "Patch 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, Visual Patch 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 patch six times (and all times after that) the message will appear and the patch 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.

Lets 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 projects 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 patch.

When you run the patch, 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 patch.

You probably wont 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 Visual Patch 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 lets dive right in.

1) Start a new project and then choose Project > Resources.

This opens the resources dialog. Click on 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 wont 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 projects 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 functions name parameter.

4) Build and run the patch.

When you run the patch, 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 patch. 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 wont 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 functions 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 projects 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 patch.

When the patch 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 patch. Edit the script in the projects 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 functions 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 patch again to try out the script again. When you're done, exit the patch.

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 Visual Patch 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 Visual Patch: Global Functions, Plugins, and Script Files.

Global Functions

The Global Functions resource in Visual Patch can be found in the design environment by choosing Project > Resources and clicking the Global Functions tab. 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 patch before the On Startup event is executed. This makes it a great place to create any functions that you want to have available throughout your project 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 patch.

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 Visual Patch 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 plugin's documentation for information on what features it adds and how to use them (click the About Plugin button to bring up the About Plugin dialog and then click the Plugin Help button).

Plugins can be added or removed from your project on the Plugins tab, which can be accessed by choosing Project > Resources and clicking on the Plugins tab in the Visual Patch design environment.

Note: Any action plugins that are located in the Includes\Plugins folder within the Visual Patch program directory will be available on the Plugins tab.

The More Plugins button is an easy way to see what plugins are currently available on the Indigo Rose website. Pressing this button will bring you to the Visual Patch plugins area of the Indigo Rose website.

If a plugin has a check in the checkbox beside its name on the plugins tab, it will be included in your patch. Since there is some overhead in terms of file size, it is recommended that you only include plugins that are needed by your patch. If you do not check the checkbox beside a plugin, it will not be included in the patch and will not take up any extra space.

Once you have included the plugin in 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 script usually with the .lua file extension. They can be added to your project on the Includes tab of the Resources dialog, which you can access by choosing Project > Resources from the program menu.

Note: All action editors in Visual Patch 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 Visual Patch except that instead of the script being kept in the Global Functions resource, it is stored externally to your project in 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 patch 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 7: Session Variables

User's Guide - Chapter 7: Session Variables

Session Variables

When designing a patch, it’s often desirable to make parts of it dynamic. For example, the user might input a value on one screen that you’d like to display on the next. Or you might want to display a path on a screen (as the default value in an edit field, perhaps), but the path includes a folder like "My Documents" that is likely to have a different location on each user’s system.

Although you could use regular script variables along with actions to manipulate the screen text at run time, session variables allow you to accomplish the same result in a more direct way: by simply including "placeholders" in your screen text that will automatically be replaced by specific values before the screen is shown.

In this chapter you will learn everything there is to know about session variables in Visual Patch.

What Are Session Variables?

Session variables are designed to handle dynamic data during the patching process. Essentially "placeholders" for changeable text, session variables give you an easy way to insert dynamic values into the text that appears on your screens.

They also give you an easy way to compose paths to locations that cannot be known in advance, such as the path to the user’s My Documents folder. For example, you can use a session variable like %MyDocumentsFolder% in a path to be replaced by the appropriate full path at run time.

Like regular variables, session variables allow you to "store" information in them, acting like named "containers" that you can assign values to. The main difference between session variables and the "regular" variables you use in scripts is simply that session variables in a screen’s text are automatically expanded before the screen is shown. This makes them especially useful for displaying dynamic text on screens.

Even though all session variables are functionally identical, there are two distinct categories of session variables that can be used in Visual Patch: built-in session variables, and custom session variables.

Built-in Session Variables

For convenience, Visual Patch contains a variety of built-in session variables for values that are commonly used in projects. These variables are automatically assigned appropriate values when the patch application is started.

Most 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 which automatically contains the correct path.

Note: Many of these values are also available in the form of global variables that you can use directly in your scripts, e.g. _WindowsFolder and _ProgramFilesFolder. There are also actions like Shell.GetFolder that you can use to get additional system paths. The built-in session variables are provided primarily for use in paths and default values that are displayed on screens.

Here is the list of built-in session variables, in alphabetical order:

%AppFolder%

The main directory where your software has been found on the user’s system. The value of this session variable is set through actions. (A default action script to determine this folder path is automatically generated for you by the project wizard.)

%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-user 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\All Users\Application Data." On Windows Vista or later, this returns "C:\ProgramData."

%CommonFilesFolder%

The user’s Common Files folder. Typically, this is something like "C:\Program Files\Common Files."

%CompanyName%

Your company’s name. 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.

%DesktopFolder%

The path to the user’s Desktop folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.

%DesktopFolderCommon%

The path to the user’s Desktop folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this is the same as %DesktopFolder%.

%FontsFolder%

The path to the user’s font directory (e.g. "C:\Windows\Fonts").

%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 2000/XP and "C:\My Documents" on Windows 98/ME, and "C:\Users\YourName\Documents" on Windows Vista or later.

%ProductName%

The name of the product that you are patching. The value of this variable is set on the Session Variables tab of the Project Settings dialog.

%ProgramFilesFolder%

The user’s Program Files folder (e.g. "C:\Program Files").

%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 patch executable was run from (e.g. "C:" or "D:").

%SourceFolder%

The full path to the folder that the patch executable was run from (e.g. "C:\Downloads" or "D:\").

%SourceFilename%

The full path, including the filename, for the current patch executable. For example, if the user was running "patch.exe" from "C:\Downloads," %SourceFilename% would be expanded to "C:\Downloads\patch.exe."

%StartFolder%

The path to the user’s Start menu folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.

%StartFolderCommon%

The path to the user’s Start menu folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this is the same as %StartFolder%.

%StartProgramsFolder%

The path to the Programs folder in the user’s Start menu. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.

%StartProgramsFolderCommon%

The path to the Programs folder in the user’s Start menu. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this is the same as %StartProgramsFolder%.

%StartupFolder%

The path to the user’s Startup folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.

%StartupFolderCommon%

The path to the user’s Startup folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this is the same as %StartupFolder%.

%SystemFolder%

The path to the user’s Windows System folder (e.g. "C:\Windows\System").

%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 Visual Patch extracts the files it will need for the patch. (For example, this is the directory where primer files are extracted.)

Usually this will be the user’s temporary directory, unless overridden 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 patch is running. The value of this variable can be changed on the Session Variables tab of the Project Settings dialog.

Custom Session Variables

You can define your own session variables to supplement the built-in session variables that are automatically provided in Visual Patch. The session variables that you define are known as "custom" session variables.

Custom session variables can be used everywhere that built-in session variables can be used; in fact, they are functionally identical. The only difference is that the built-in session variables are automatically created for you in each project, whereas custom session variables don’t exist until you assign a value to them.

Setting Session Variables

Each session variable consists of a name, e.g. "%ProductName%," and a value that you assign to it, e.g. "Widget Master 2.0." When a session variable is expanded at run time, its name is replaced by the value that is currently assigned to it. (For example, "Thank you for using %ProductName%" would become "Thank you for using Widget Master 2.0.")

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 project.

Using the Session Variables Tab

The Session Variables tab provides a convenient location for setting the initial value of session variables at startup. It is primarily used for values that need to be displayed on screens and that don’t need to be determined dynamically at run time using actions. In other words, it is where you can specify values that you know in advance and that you want to display on the earliest screens in your project.

The Session Variables tab is located on the Project Settings dialog, which you can access by choosing Project > Settings from the program menu.

The Session Variables tab contains two categories: Product Information and Custom.

The Product Information category contains built-in session variables for values that are commonly displayed on screens, such as the product name and the name of the company that produced it. To set the value of one of these variables, simply edit the appropriate field in the right-hand column.

The Custom category is where you can add, remove and edit your own session variables to supplement the ones in the Product Information category. To add a custom session variable, click on the Add button at the bottom of the dialog.

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. It allows you to set the value of an existing session variable that was defined on the Session Variables tab, or to create a brand new one.

The SessionVar.Set action can be used with any event (i.e. in any script) 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, including built-in session variables like %MyDocumentsFolder%. 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.

Removing Session Variables

When you remove a session variable from your project, Visual Patch 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 the patching process with an action. The action used to remove a session variable is called SessionVar.Remove. The function prototype for this action can be seen below:

SessionVar.Remove(string VariableName)

For example, if you wanted 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

The main use of session variables is for the dynamic expansion of text strings on screens. 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 where 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 on one screen that needs to be displayed on another screen. In this case, the values are not known until some point during the patching process, and therefore could not be directly entered at design time.

Tip: Session variables can also be useful in multilingual patches for custom messages that you wish to display depending on the language detected or chosen.

When Are Session Variables Expanded?

Session variables are automatically expanded before each screen is shown-specifically, before each screen’s On Preload event. Any session variable that is used on a screen will automatically display the value it contained before that screen was shown.

This means that if you change the value of a session variable in a screen’s On Preload event, in most cases the old value will still appear. There are a few exceptions, such as some static text controls which will automatically be "refreshed" after the On Preload event and will therefore display their new values. As a general rule, however, the On Preload event is already "too late" for any changes to a session variable to be made if you want the new value to automatically appear on the screen.

One way to get the current value from a session variable is to expand it "manually" using the SessionVar.Expand action. SessionVar.Expand allows you to retrieve the current value of a session variable at any point in your project. In fact, you can use SessionVar.Expand on a screen’s On Preload event to retrieve a session variable’s value, and then use actions to replace the screen text with new text that includes the current value.

Expanding Session Variables in Scripts

Session variables are often used on screens that gather information from the user. For example, the Edit Fields screen stores the user’s input in separate session variables-one session variable for each edit field on the screen. This is fine if you simply want to display the user’s input on another screen; in that case, all you need to do is include the appropriate session variables in that other screen’s text. If you want to use the inputted values in your scripts, however, you need a way to expand the session variables in your script. This can easily be accomplished using the SessionVar.Expand action.

The function prototype for this action is:

string SessionVar.Expand(string Text);

Basically, the SessionVar.Expand action takes a string of text and gives you back the same text, but with all of the session variables in the string expanded. In other words, it returns a copy of the text in which all of the session variables have been replaced by their current values.

For example, if a session variable called %MyName% contains the string "They call me nobody," you can access the string using the following action script:

strContents = SessionVar.Expand("%MyName%");

In the above line of script, the variable strContents would receive an expanded version of "%MyName%." The end result is that the value stored in %MyName% ("They call me nobody") would be assigned to strContents.

However, SessionVar.Expand isn’t limited to retrieving the contents of a single session variable. It will happily expand a string containing several session variables-or even one containing no session variables at all. (In the latter case, the string it returns will be an exact copy of the original string.)

For example, using SessionVar.Expand on the string "When asked for his name, all he said was: %MyName%" would return the entire string with the expanded contents of the session variable %MyName%:

When asked for his name, all he said was: They call me Nobody

In addition, when the SessionVar.Expand action expands a string, it performs a recursive expansion. Session variables within session variables are expanded as well. This means that if the value in a session variable is a string that has a session variable in it, the "internal" session variable will also be expanded. You can think of the expansion as being a "loop" that continues until there are no more session variables left to expand.

For example, consider the following two session variables:

%verb% - whose value is "flying"
%message% - whose value is "Look at me, I’m %verb%!"

After the following action script is executed:

strContents = SessionVar.Expand("%message%");

…the contents of the variable strContents would be:

Look at me, I’m flying!

As you can see, %message% was replaced by "Look at me, I’m %verb%!" and then %verb% was replaced by "flying."

Expanding Without Recursion

Visual Patch also contains an action that will prevent the recursive expansion of session variables. This action is called SessionVar.Get, and its function prototype is:

string SessionVar.Get(string Text);

Using the previous example, let’s say we only wanted to expand the contents of %message%, without expanding %verb%. In that case, the following action script could be used:

strContents = SessionVar.Get("%message%");

…and the contents of the variable strContents would be:

Look at me, I’m %verb%!

As you can see, the SessionVar.Get action would expand the %message% session variable, but wouldn’t go any further; the %verb% variable would remain unexpanded.

Expanding after On Preload

Session variables are automatically expanded before each screen is shown. This automatic expansion happens before any of the screen’s events are triggered-even before the earliest screen event, On Preload. This means that if you use the SessionVar.Set action to change the value of a session variable from On Preload, the new value will not appear on the screen, because at that point the session variables have already been expanded. (There are exceptions to this rule, such as the static text controls on some screens, but it is safer to assume that it is true in all cases.)

In order to change the text on a screen from within that screen’s events, you must use a different method. Luckily, there are two ways in which you can expand session variables on the current screen.

The first and most straightforward method is to formulate a new text string with the session variable in it, expand that string using SessionVar.Expand, and then assign the expanded string to the desired screen control.

For example, the following script would expand a string that contains two session variables and then replace the text on a scrolling text screen with the new text:

NewText = SessionVar.Expand("First: %FirstName%\r\nLast:
 %LastName%");
DlgScrollingText.SetProperties(CTRL_SCROLLTEXT_BODY, {Text=NewText});

Although this method works well, it requires you to write and edit the text within your script, instead of composing the text directly on the Settings tab for that screen. This isn’t too difficult if your project only supports one language. However, if you’re creating a multilingual project, you’ll need to use control structures to assign different text to the screen that is appropriate for the user’s system language. This would make your scripts much longer and more difficult to maintain.

An alternative method is to use an action to retrieve the original text for the screen, which still contains the session variables in their unexpanded form. This allows your script to essentially "re-expand" the text that you entered on the Settings tab.

Here is a version of the previous script that uses the Screen.GetLocalizedString action to retrieve the original unexpanded text for the scrolling text control:

OriginalText = Screen.GetLocalizedString(IDS_CTRL_SCROLLTEXT_BODY);
NewText = SessionVar.Expand(OriginalText);
DlgScrollingText.SetProperties(CTRL_SCROLLTEXT_BODY, {Text=NewText});

The key to this second approach is the Screen.GetLocalizedString action, which retrieves the text for a specific screen control as it was entered on the Settings tab, automatically choosing the appropriate text for the language on the user's system.

When your project supports multiple languages, it is much easier to edit the screen text directly on the Settings tab, where you can use the language selector to switch between all of the languages that your project supports.

Tip: If you would like to see an advanced example of session variables in use, examine some of Visual Patch’s built-in screens. For example, the Select Drive screen uses actions to set, update, and display the session variable %SpaceAvailable%.


Chapter 8: Languages

User's Guide - Chapter 8: Languages

Languages

The Internet has opened many new markets to software developers whose past products would usually have supported only their own local language. In the international marketplace, it is important not only to offer software in a variety of languages, but also to keep this software current.

As you’ll see in this chapter, you can use Visual Patch to create a patch that will automatically display messages and prompts in your user’s native language. With integrated language selection built into all screen dialogs, Visual Patch also makes it very easy to modify your existing translations at any time.

Internationalizing Your Patch

Visual Patch has the ability to automatically detect the user’s system’s language and to display messages and screens in that language. As the developer, you have full control over which languages are supported in your project and over the content that you would like presented to the user.

Language text is mainly used for messages generated throughout the patching process and on screens, both of which can be easily translated for multilingual patches.

Visual Patch allows you to localize your patch application in two areas:

· Common error messages, status messages and prompts

· Application-specific screens

The following sections of this chapter will look more closely at how to achieve this localization.

Run-time Language Detection

The language that the patch application 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. The settings are 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 then launch 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 that is used in a country or geographical region. Each language identifier is made up of a primary and secondary language ID. (There is a complete list of primary and secondary language IDs in the Visual Patch help file.)

Visual Patch maps all known languages and sub-languages according to the language identifiers used by Windows. These mappings exist in a file called language_map.xml located in Visual Patch’s Language folder (usually "C:\Program Files\Visual Patch 3.0\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 patch 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 project’s default language as well as which languages are supported by your patch. For example, if you are editing one of your screens and decide that you would like to add a German translation, you will have to use the Language Manager to do so. Once you add German support here, it will be available in all other areas of your project.

When you add a language to your project, you are indicating that you want the patch application to recognize that particular language identifier on a system and to use specific messages for that language when identified. Conversely, if a system’s language is not represented in the languages list, it does not mean that the patch will not run on that system; rather, it means that the patch will use the default language.

Default Language

Every project must have a default language. The default language is the one that will be used when the patch application encounters a system language that is not represented in the languages list.

For example, let’s suppose that you have English, French and German support in your project with English as the default language. If your user runs the patch 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 of the "internal" error messages, status messages and prompts that are used by the patch application. Language files do not contain project-specific messages, such as the text that you enter on screens.

The language files are located in Visual Patch’s Languages folder (usually "C:\Program Files\Visual Patch 3.0\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.

Not all languages have a pre-configured language file. 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 Visual Patch, please visit the Indigo Rose website (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 you would create a French language file like the one that ships with Visual Patch:

1. Open Windows Explorer to Visual Patch’s Languages folder (usually "C:\Program Files\Visual Patch 3.0\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 as well.

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 Visual Patch 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 Visual Patch. The new language will now be available.

Adding Languages

To add a new language to your patch, 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 project, the following happens automatically:

· Visual Patch 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 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 Screens dialogs to verify and/or translate the text for the new language.

Removing Languages

To remove a language from the project, select it in the Language Manager’s list and click the Remove button.

Note that the default language cannot be removed. In order to remove a language that is currently being used as the default language for a project, you will need to make another language the default language first.

When you remove a language, all of the translations for that language are removed from the screens in the project. Therefore, use caution when removing languages.

The Language Selector

Once a language is added to your project, it is available for translation. When you’re editing the text on a screen, you can select the language that you want to edit by using the language selector. The language selector is simply a drop-down list that lets you choose the current language (for editing purposes) of the screen.

For example, if your project supports English, French and German, the language selector on every screen’s properties dialog will let you choose whether to edit the English, French, or German text.

Selecting a language in the language selector replaces the editable text on the dialog with the text for that language. Any changes that you make to the screen text will be restricted to that language.

Note: If you select a newly added language for which there is no language file, the editable text will initially be the same as the text for the default language.

Only the languages that have been added to the project will appear in the language selector. If you want to work on a language that is not in the drop-down list, you will first have to add it to the project using the Language Manager.

Localizing Screens

To localize a screen, open the Screens dialog (Project > Screens) and double-click on a screen to open the screen’s properties. Next, select the language that you want to edit in the language selector. Then, simply type the text that you want for the various fields in that language.

Note: 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 user.

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.

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 Visual Patch, 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 Visual Patch or that you need to work with the project in other ways while the translation is taking place. Visual Patch has a solution for this situation. You can:

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. In the popup menu, select Export Language followed by the language that you want to export.

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 click Open.

10. You will now have the new translated strings in your screen.

Customizing Error Messages and Prompts

If you want to change the default error messages, prompts or status messages, you can edit the appropriate XML file in the Languages folder using a text editor such as Notepad. However, this is not generally recommended; the messages that you change will be propagated to all projects that are built after the changes are made.

Note also that if you choose to change default messages, your modified language file may be overwritten by a future update to Visual Patch. To avoid this, you may want to rename any language files that you modify, for example you might rename english.xml to my_english.xml. (In cases where there is more than one language file for a given language, Visual Patch will use the last one that it finds in the Languages folder.)

Advanced Techniques

There are a number of advanced techniques that you can use to manipulate the language and the translated language strings in your patch 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.GetLanguage. 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 Visual Patch 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 if…then statements to open the appropriate site:

-- Determine the absolute system language
local tblSysLang = System.GetDefaultLangID();

-- Set a default
local strURL = "http://www.yourcompany.com/english");

-- See if we should go 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

-- Go to the Web site
File.OpenURL(strURL);

Application.GetLanguage

Application.GetLanguage is used to retrieve the primary and secondary language ID that is actually being used by the patch application. Note that Application.GetLanguage may return a different result than System.GetDefaultLangID if the language being used by the patch differs from the language your user employs in Windows.

For example, let’s say that you have three languages in your project: English (which is the default language), French, and German. Suppose a user from Chile runs the patch on their system. Even though their system uses primary ID 10 and secondary ID 13 (which would be returned by System.GetDefaultLangID), Application.GetLanguage would return a primary ID of 9 and a secondary ID of 1, which is the project’s default language (English). The patch application would be using the default language because Spanish was not added to the project.

The value returned by Application.GetLanguage will always correspond to a language that you added to your project using the Language Manager. It will never identify languages that were not explicitly included in the project.

Changing the Current Language

Normally, if the patch application detects a language on the user’s system that is not supported in the Language Manager, the default language will be used. However, you may prefer to have your update use a different language in such situations. You can accomplish this by using the Application.SetLanguage action.

The Application.SetLanguage action allows you to directly set the primary and secondary language IDs that will be used for the patch. Calling this action changes all subsequent error and status messages as well as the text shown on the screens. It effectively "forces" the patch application to act like it detected that language in the first place.

For example, let’s say that your project supports two languages: English (which is the default language) and Simplified Chinese. Since English is the default language, it will be used whenever the patch is run on anything other than Simplified Chinese.

However, you might prefer that the patch application use Simplified Chinese if the user runs it on a system configured to use Traditional Chinese.

In other words, you want to override the default language rule and force your patch application to use Simplified Chinese whenever Traditional Chinese is detected. You can do so easily by placing the following short script at the beginning of the On Startup event, before any dialogs are shown:

-- Determine the 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.SetLanguage(4, 2);
end

Testing Different Languages

You may also want to use the Application.SetLanguage action for testing purposes. For example, if you are running an English version of Windows, you might want to see how your patch will look on an Italian system. Because your system is running in English, the patch application will always choose English as the language to display when you run it on your system. However, you could force the patch to use Italian by putting the following script at the beginning of your On Startup event:

Application.SetLanguage(16, 1);

You could even modify your On Startup script to check for a custom command line option, so you could force your patch application to use a different language at any time. This could be useful for testing purposes, or to handle any language detection issues that are discovered after the patch has been distributed.

Tip: The global variable _CommandLineArgs can be used to determine what arguments were passed to the patch executable.

Localizing Actions

You may have noticed that there is no language selector when editing scripts in Visual Patch. Any text you enter directly into a script will remain the same, regardless of what language is detected on the user’s system.

However, it is possible to use actions to detect the current language, and to use multiple "if" statements to specify different text for different languages. For example, let’s say that your project 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 patch application is using, and then displays one of two possible greetings:

local tblSysLang = Application.GetLanguage();

if (tblSysLang.Primary == 9) then
Dialog.Message("Welcome",
"Welcome to the patch");
end

if (tblSysLang.Primary == 12) then
Dialog.Message("Bienvenue",
"Bienvenue au programme de correction");
end

The Application.GetLanguage action returns a table containing the primary and secondary language ID that is being used by the patch application. Note that this may or may not be the exact language that was detected on the user’s system; rather, it is the appropriate language that the patch application has chosen from the list of supported languages in the project. In other words, it is the user’s system language if that language is supported by the patch; otherwise, it is the default language.

Tip: You can get the user’s actual system language by using the System.GetDefaultLangID action. However, it is usually preferable to use the Application.GetLanguage action so the scripted language behavior will match the "automatic" language behavior of the screens and error messages in the project.

Working with Existing Translated Messages

Visual Patch allows you to get and set translated messages from the language files and screens at run time. This is done using the following actions.

VisualPatch.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 language currently being used by the patch application. For example, the default language files provide confirmation messages that can be used if the user wants to abort the patching process. Here is a way to show a dialog that asks the user for confirmation in the current language before exiting:

local strTitle = VisualPatch.GetLocalizedString("MSG_CONFIRM");
local strPrompt = VisualPatch.GetLocalizedString("MSG_CONFIRM_ABORT");
local nResult = Dialog.Message( strTitle
, strPrompt
, MB_YESNO
, MB_ICONQUESTION
, MB_DEFBUTTON2 );

if(nResult == IDYES)then
Application.Exit();
end

VisualPatch.SetLocalizedString

This action allows you to change the value of a localized string. This can be useful if you want to override the default value of an error message from script, so you don’t have to permanently change your language file. For example, let’s say that you want to change the message that is displayed if the user tries to cancel the patch. By default it is "The patch 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?"

VisualPatch.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 value of a localized string from the current screen’s message file. Every editable text item on a screen has a corresponding string ID that is used internally to retrieve the appropriate text for the current language when the screen is displayed.

The actions can also be used to create new, temporary localized strings that are only valid on the current screen, by using custom string IDs. For example, you could create a number of custom localized error messages to be used in the screen’s event scripts, without having to implement "if…then" branching wherever an error message was displayed.

Note: The Screen.GetLocalizedString and Screen.SetLocalizedString actions work the same way that VisualPatch.GetLocalizedString and VisualPatch.SetLocalizedString do, except that they will only access strings used on the current screen.


Chapter 9: Building and Distributing

User's Guide - Chapter 9: Building and Distributing

Building and Distributing.

Once you have created your Visual Patch project and configured all relevant options, the only two steps left are to build your patch and distribute it.

Building your patch is made easy using the built-in Publish Wizard. For more advanced cases, you can customize the build process through the Build Settings dialog, which gives you access to many advanced features such as build configurations and pre/post build steps. Whatever route you choose, Visual Patch makes building your patch a seamless part of the development process.

Once your patch is built, you must distribute it to your users. This chapter will introduce you to both the standard and advanced aspects of the build process, and will get you well on your way to distributing your patch

The Build Process

Visual Patch’s ultimate goal is to produce the smallest patch possible. When you choose to build your patch, all of the files in your included versions are first verified and then analyzed. Visual Patch begins analyzing at the latest version in your patch, and compares all previous versions’ files to the ones in the latest version.

Depending on what the previous versions contain, files listed in the most current version are either not included in the final patch, are partially included in the form of diff files, or are included in their entirety. This ensures that the patch is of the smallest size possible while maintaining compatibility with all desired previous versions.

After analyzing all of the included files, diff files are created for any file existing in all versions but which is not the same across all versions. These diff files are created using Indigo Rose’s proprietary binary differencing compression engine. If a file exists in the latest version that does not exist in one or more previous versions, the complete file is included in the patch. Lastly, if a file exists in all versions, and is unchanged across all versions, it is not included in the patch.

During the build process, the files to be included – both diff files and complete files – are compressed into the final single patch executable. It is important to note that the sum of the diff file sizes will never be greater than the individual file’s calculated compressed file size. In other words, if Visual Patch can create a smaller patch by simply compressing an entire file rather than including diff files, it will include the entire file.

The Publish Wizard

With the goal of making the build process as seamless as possible, Visual Patch includes a Publish Wizard to assist you.

The first 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.

Note: If your 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 allows you to select which versions will be built into your patch.

This is a very important step in the build process. It allows you to individually include or exclude each of the versions in your project from the built patch executable.

Being able to specify which versions are included in your patch is extremely useful. For example, imagine you have a product that has been updated fifteen times. Including all of these versions in your patch could potentially result in a rather large patch. On the other hand, creating a patch that applies only to the last three previous versions would be a substantially smaller file.

The wonderful thing about the Visual Patch build process is you don’t have to choose between building a complete full history patch and building a patch applicable to only a few of your past versions. Build one, launch the build wizard again, and easily build the other! Then, let the user decide which patch they should download, or better yet, incorporate TrueUpdate (www.trueupdate.com) into your software and have that decision made automatically, without any user interaction required.

When the Next button is clicked, Visual Patch begins building the patch.

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 click Finish to dismiss the build wizard. If the Open output folder option is checked, the output folder will be opened automatically, giving you instant access to the generated files.

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 patch file is found here. If you opted to publish without using the publish wizard, this is where you must specify your build settings. These settings are organized into tabbed sections in the Build Settings dialog: Output, Constants, Pre/Post Build, and Optimizations.

Output

All of your patch output settings are located on this tab. You can specify where your final patch executable will be built to by adjusting the Location settings. Enabling the encrypt patch archive data option encrypts your patch data with a random key during the build process, helping to hide and further protect your information. The Versions to Build setting allows you to specify which versions will be built into the final patch executable.

Constants

Constants are essentially design time variables. They are similar to session variables, but instead of being expanded as the user runs the patch, 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.

Clicking the Add button displays a dialog where you can name the constant and give it a value.

Each constant has a name that begins and ends with a # sign, and an associated value. The name will be replaced by this value throughout the project when it 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.

Build Configurations

One of the many timesaving features of Visual Patch is the ability to define build configurations. Build configurations allow you to define different build settings for your project and switch between them easily.

For example, it’s often useful to have a build configuration for each type of patch that you wish to build. One build configuration could create a full-history patch, capable of updating all previous versions (e.g. 1.0, 1.1, 1.2, 1.3, 1.4) up to the current version. Another could be an incremental patch to bring the previous version up to the current one (e.g. from 1.4 to 1.5). A third could be a multi-version patch to bring two common previous versions up to the latest version (e.g. from 1.2 or 1.3 to 1.5). You could then build each type of patch by switching between the build configurations.

Note: Files and folders can also be associated with specific build configurations on their Conditions tab. This makes it easy to conditionally enable or disable the patching of specific files within a version.

You can add a build configuration to the current project by clicking the Add button near the top of the Constants tab of the Build Settings dialog.

Constants and 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 (professional version vs. standard version patch)

· 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

Constants and 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 patch for every one of your customers, with the customer’s name showing up on one or all of the screens during the patch.

For more information on performing unattended builds of your project, search for "Unattended Build Options" in the Visual Patch help file.

Pre/Post Build.

There may be instances where you want to run a program either before or after you build your patch. Visual Patch 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, launch a program that would compare all files from your company’s development network to the files about to be patched to ensure the most up-to-date files are included – the program could alert you if the local files do not match those on the network. You would want this program run at the last possible second to ensure last-minute bug fixes are not left out. Alternatively, you could have Visual Patch call an FTP client program with command line arguments to automatically upload your latest patch to your website. 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 Visual Patch to ‘sleep’ while the other program is open, check the Wait for program to finish running checkbox.

Optimizations

There are a number of size and speed optimizations on the build settings dialog that allow some control over the build process. For example, enabling the "Cache diff files" and "Cache compressed file sizes" options allow Visual Patch to store any binary difference files that it creates so it only needs to perform the delta compression once for each file, instead of every time the patch is built.

Enabling the "Cache diff files" option stores the generated diff files in a folder on your system so they can be reused the next time you build, instead of having to be generated again. Subsequent builds of the same project are much faster when this option is enabled.

Likewise, Visual Patch calculates the compressed file size of each file and compares this value to the total size of all the diff files that are generated for that file. Enabling the "Cache compressed file sizes" option stores the compressed size information so it doesn’t need to be recalculated the next time you build the project.

The Multipass Diff Creation options determine whether Visual Patch will perform multiple passes on each file in order to achieve the smallest possible diff size. Each successive pass will look for longer patterns in the file, which, depending on the internal structure of the file, may result in better compression.

Since each pass adds to the creation time, you can limit the multipass optimization so it is only performed when the initial pass takes less than a specific amount of time. This is known as the "Initial pass time threshold."

The "Maximum additional passes" option controls the maximum number of additional passes that will be attempted in order to search for successively longer patterns.

Tip: For best results, enable the "Cache diff files" option and set the "Initial pass time threshold" to 0 so the multipass optimization will be performed for every file, but only the first time you build the project. This will allow Visual Patch to generate the smallest diff files, and will still allow subsequent builds to be performed as quickly as possible.

The Low Memory Scenario options allow you decide how you want Visual Patch to behave in low memory situations. You can choose to favor small patch sizes or shorter build times. In general, it is best to keep this set to "Minimize patch size," however you may wish to change the setting on systems with limited memory resources if you find that your builds are taking a very long time to complete.

Tip: For large files, the size of the generated diff files depends on your computer’s available memory. Because of this, it is recommended that you clear out the diff cache by clicking on the Clear Cache button whenever your computer hardware is upgraded.

Build Preferences

To control how Visual Patch handles the build process, you can modify the build preferences by choosing Edit > Preferences from the menu.

You can use the build preferences to control whether Visual Patch opens the output folder by default, disable the publish wizard and, when not using the wizard, control whether a confirmation dialog is displayed before the build process begins.

Testing Your Patch

One of the most important and often overlooked steps when creating a patch is testing it after it has been built. You should test your patch on as many computers and operating systems as possible. Try it on every operating system that your software product supports. All versions of windows have differences between them, and should be thoroughly tested. As well, test your patch on systems with a lot of hard-drive space and on those with a very limited amount of hard drive space. And lastly, test your patch on a system where the defaults for your program’s installation were not used. For example, install your software to C:\SomeDirectory\ and then patch it. Does your patch fail, or does it work as expected?

If you have made use of Visual Patch’s multilingual support, be sure to test out each language in your install.

Many problems with patches have simple causes, such as forgetting to include a file, or moving a file to an incorrect location. Often a runtime problem is simply due to the patch being unable to locate the files to patch. Care must be taken when designing the directory structure of your patch, ensuring that it is compatible with the installed software being patched.

If you do run into a problem with your patch, 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 patch to fail.

Tip: For information related to tracking down script-related issues, see Debugging Your Scripts in Chapter 10.

Distributing Your Patch

Once you have thoroughly tested your patch, it is time to distribute it. There are several ways to distribute your software patch, but the four main media are floppy disks, CD-ROMs, DVDs, and the Internet.

Preparing your patch for distribution is as easy as publishing to a hard drive folder. Once the build operation has completed, simply copy the patch executable to your desired media, and you are ready to go! Or, if you have opted to distribute via the Internet, simply take the generated patch file and upload it onto your website for your customers to download.

For an automated patch delivery system, consider TrueUpdate. TrueUpdate incorporates easily into any windows-based application, and allows the user to check for updates through your software application. Or, your application could use TrueUpdate to check for updates periodically. TrueUpdate supports either a wizard, dialog, or silent interface.

TrueUpdate isn’t just an easy way to let your customers know software updates are available; it can automatically select the best patch to apply. For example, consider a product that has experienced fifteen version changes. You may choose to publish one full history patch, and one patch that updates the last three versions to the most current version. TrueUpdate can check the user’s version and download the appropriate patch, potentially saving you bandwidth costs and your users time.

For more information on TrueUpdate, please contact Indigo Rose Software or visit the TrueUpdate website at www.trueupdate.com.


Scripting Guide

Contents

Welcome to the online version of the Visual Patch Scripting Guide.

Tip: A printable (PDF) version of this guide is contained in the user's guide, which can be accessed from the Start menu. A printed and perfect-bound version of the user's guide is also available and can be ordered directly from www.ondemandmanuals.com.

Introduction

A Quick Example of Scripting in Visual Patch

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

Visual Patch Web Site

Indigo Rose Technical Support

The Lua Web Site


Introduction

One of the powerful features of Visual Patch is its scripting engine. This document will introduce you to the scripting environment and language.

Visual Patch 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 Visual Patch action called “Dialog.Message” to display a message to the user.

New programmers and experienced coders alike will find that Visual Patch is a powerful, flexible yet simple scripting environment to work in.

Before You Begin

In order to try out the example scripts in this chapter, you will need a basic project that you can build so you can run the patch application and see the scripts in action.

If you already have a Visual Patch project established, you can use a copy of it for this purpose. (Definitely use a copy of the project, though, so you can modify its scripts freely.)

Alternatively, you can create a simple project to use just for trying out your scripts.

All you need is a project that you can successfully build. Even if you have no intention of ever publishing the project, it will need a few items in order to get past the various checks performed during the build process.

The minimum, therefore, is a project with:

  • at least two version tabs

  • at least one file on each tab

  • at least one key file on each tab

By default, every new project in Visual Patch has some standard scripts that provide default functionality and serve as a starting point for the project. For the purposes of this chapter, however, you will want to remove the default actions.

You can remove a default script just like you would remove any text in a text editor: simply select the text (e.g. press Ctrl+A to select it all) and press the Delete key.

The examples in this chapter assume that you have removed the default script from the On Startup event (Project > Actions) and that the project can build successfully.

Tip: If you want to test actions in the On Startup event without proceeding with the rest of the patching process, add an Application.Exit() action to the end of your script for that event. This action will immediately exit from the patch application as soon as it is encountered in the script.

A Quick Example of Scripting in Visual Patch

Here is a short tutorial showing you how to enter a script into Visual Patch and preview the results:

1. Set up a new project as described in the previous section Before You Begin.

2. In the On Startup event (Project > Actions), add the following line:
Dialog.Message("Title", "Hello World");

It should look like this when you’re done:

3. Click OK to close the action editor.

4. Choose Publish > Build from the menu and go through the publish wizard.

5. Once you have built the patch, run it so the script you entered is 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 Visual Patch Application. You can use the above method to try out any script you want in Visual Patch .

Note: If you are working with actions that interact with screens, you will need to perform the actions from a screen event.


Important Scripting Concepts

There are a few important things that you should know about the Visual Patch 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 on page 12), 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 Visual Patch is concerned.

The same principle applies to function names as well. For example:

Dialog.Message("Hi", "Hello World");

...refers to a built-in Visual Patch 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 Visual Patch. 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 Visual Patch 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 the project's On Startup event, and then enter:

Dialog.Message("The value is:", foo);

...into a screen's On Preload event, the second script will use the value that was assigned to “foo” in the first script. As a result, when the screen is shown, 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 project's On Startup event is triggered before the screen's On Preload event, so the value 10 is already assigned to foo when the 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

Visual Patch’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 Visual Patch 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 Visual Patch: 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”). Visual Patch 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 page 42.

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 page 38.

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 on page 30):

Example 1:

guys = {"Adam", "Brett", "Darryl"};
Dialog.Message("Second Name in the List", guys[2]);

This will display a message box with the word “Brett” 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 page 35.

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)
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 Visual Patch 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 on page 34.


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 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 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 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 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 Visual Patch 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 patch, 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 patch in any other script.

This brings up an important point about scripting in Visual Patch. 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 screen button’s 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 Project > Resources... from the program menu and select the Global Functions tab.)

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 Visual Patch 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 Visual Patch , 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. Or you could simply use the built-in String.CompareNoCase action. 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 patch.

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);

So, for example, even if you do two requires in a row:

require(SessionVar.Expand("%TempLaunchFolder%\\MyScript.lua"));
require(SessionVar.Expand("%TempLaunchFolder%\\MyScript.lua")); -- 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.

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,” or “function.” 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

Visual Patch 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 Visual Patch as smartly and effectively as possible!

This section will explain Visual Patch’s error handling methods as well as cover a number of debugging techniques.

Error Handling

All of the built-in Visual Patch 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 Visual Patch'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 Visual Patch 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 Visual Patch 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 Visual Patch’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

Visual Patch 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 patch. 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 Visual Patch 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 patch, 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 patch, 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

Visual Patch 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 patch, 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 Visual Patch. 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 Visual Patch.

Help File

The Visual Patch help file is packed with good reference material for all of the actions and events supported by Visual Patch, and for the design environment itself. You can access the help file at any time by choosing Help > Visual Patch 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 Visual Patch. 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 > Visual Patch User's Guide from the menu.

Visual Patch Web Site

The Visual Patch Web site is located at http://www.visualpatch.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

Visual Patch’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 Visual Patch that are not officially supported in Visual Patch. These functions, if any, are documented in the Lua 5.0 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 Visual Patch. 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 Visual Patch'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 patch. 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 patch won't have a value when your it 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 patching, UserName won't have a value before patching.

    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, its 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 patch will either generate an error or not behave as you intended. (This is why it's important to test your project 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 patch, 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 Visual Patch. 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 Visual Patch, 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 Visual Patch scripts easier to read.

Unless they are contained within a string, whitespace characters (like spaces and tabs) are completely ignored by the patch 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.

Visual Patch'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?


Actions - Overview

Actions

Overview Alphabetical List Error Codes

What are actions?

Actions are the commands that your Visual Patch patcher can perform at run time. Each action is a discrete instruction that tells the patch 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 patch do stuff.

And there's a lot of stuff your patch 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 patch. 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 two types of events in Visual Patch: project events and screen events. Below is an example of the screen events:

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.

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.GetLanguage

Application.GetLastError

Application.GetWndHandle

Application.LoadActionPlugin

Application.LoadScript

Application.LoadValue

Application.Minimize

Application.Restore

Application.RunScriptFile

Application.SaveValue

Application.SetLanguage

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.SetTraceMode

Debug.ShowWindow

Dialog

Dialog.ComboBox

Dialog.FileBrowse

Dialog.FolderBrowse

Dialog.Input

Dialog.MaskedInput

Dialog.Message

Dialog.PasswordInput

Dialog.SplashImage

Dialog.TimedMessage

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

DlgGROUPBOX

DlgGroupBox.GetProperties

DlgGroupBox.SetProperties

Dlgeditfield

DlgEditField.GetProperties

DlgEditField.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

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

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

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.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

VisualPatch

VisualPatch.CheckFolderVersion

VisualPatch.GetLocalizedString

VisualPatch.GetTargetVersion

VisualPatch.SetLocalizedString

VisualPatch.WriteToLogFile

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 patch and returns an optional return code.

Tip: You can use this action to exit the patching 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.GetLanguage

table Application.GetLanguage (

)

Description

Returns a table containing the primary and secondary language ID that is being used by your patch. The value returned by Application.GetLanguage 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 patch.

Note: This action may return a different result than System.GetDefaultLangID.

Parameters

None.

Returns

(table) A table containing the current patch 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 patch 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 patch, whether a background window is visible or not.

Parameters

None.

Returns

(number) The numeric window handle for the patch. 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.


Application.LoadActionPlugin

Application.LoadActionPlugin (

string Filename )

Description

Loads an action plugin file (.lmd).

Note: Normally you would choose Project > Resources... and then select the Plugins tab 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.

Action plugins allow you to extend the functionality of Visual Patch 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 patch, 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 Visual Patch 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 patch window to the task bar.

Note: This action is the same as pressing the minimize button ( [image] ) on the patch'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 patch'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 patch'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 Visual Patch 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.SetLanguage

Application.SetLanguage (

number Primary,

number Secondary )

Description

Sets the specified language to be the patch 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 patch.

Secondary

(number) The secondary language ID of the language (in decimal format) you want to set for the patch.

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 patch to sleep for a desired period of time.

Note: While sleeping, the patch will not respond to mouse movements, clicks, or key presses. This applies to every aspect of the patch, 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. "Ready to Patch > 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.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.


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.


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 Visual Patch'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 Visual Patch, 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 | Visual Patch will interpret the function's return value as a 16-bit integer (int).
DLL_RETURN_TYPE_LONG | 1 | Visual Patch will interpret the function's return value as a 32-bit integer (long).
DLL_RETURN_TYPE_STRING | 2 | Visual Patch 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 Visual Patch 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.

Note: On Windows 95/98/ME systems, the filename cannot contain long path or file names, i.e., the path must conform to the DOS 8.3 naming convention. Windows NT, 2000, XP, Vista or later do not suffer from this limitation; however, if your patch needs to run on Windows 95, 98 or ME, you will need to use the DOS 8.3 naming convention to ensure that the action will work for all users."

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 and 2000.") 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.

Note: On Windows 95/98/ME systems, the destination cannot contain long path or file names, i.e., the destination path must conform to the DOS 8.3 naming convention. Windows NT, 2000, XP, Vista or later do not suffer from this limitation; however, if your patch needs to run on Windows 95, 98 or ME, you will need to use the DOS 8.3 naming convention to ensure that the action will work for all users."

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.

Note: This action only works on operating systems that support user profiles, therefore it is only supported on Windows 2000, Windows Server Windows XP, Windows Vista, or later. It is not supported on non-NT operating systems such as Windows 95/98/ME.

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.


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 patch.

Parameters

None.

Returns

(string) The path to the "current folder" (working directory) for the patch. 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 patch'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.

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.

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.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.

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.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.

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.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.

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.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.

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.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 2000 and 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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.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.

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.

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.

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.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.

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.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\\0s=YYN\\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. Visual Patch 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, Visual Patch 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.

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 patch.

For example, if you created this action on one of the Before Patching screens, the patch would skip any Before Patching screens that follow it and start executing the actions on the On Pre Patch actions tab, which is the next patch stage.

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
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
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 patch given a screen name.

Note: This action can be used to jump forward or backward in the patch, however the target screen must be located in the current screen list. For example, if your current screen is located in the Before Patching list, the target screen must also be located in that list. You cannot just from a Before Patching screen to an After Patching screen.

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 patch will move on to the next patch stage. For example, if the current screen is the last screen listed in the Before Patching list and this action is called, the next patch stage will begin, which are the actions on the On Pre Patch actions tab.

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.

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 Patching or After Patching 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.


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 = "" )

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. This parameter is only supported on Windows 2000, Windows XP, Windows Vista or later. On operating systems that do not support the information, it will be ignored.

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 systems prior to Windows 2000, the default verb is used if it is valid and available in the registry. If not, the "open" verb is used.
- For Windows 2000 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." Only available on Windows XP/Vista or later.
SHF_MYPICTURES | 39 | The path to the user's My Pictures folder. For example "C:\Documents and Settings\username\My Documents\My Pictures." Only available on Windows 98 SE or later with minimum IE 5.0 installed.
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." Only available on Windows XP/Vista or later.
SHF_MYVIDEOS | 14 | The path to the user's My Videos folder. For example "C:\Documents and Settings\username\My Documents\My Videos." Only available on Windows XP/Vista or later.
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." Only available on Windows XP/Vista or later.
SHF_DESKTOP | 16 | The path to the user's Desktop directory. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.
SHF_DESKTOP_COMMON | 25 | The path to the user's Desktop folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this will simply be the path to the user's Desktop folder (same as SHF_DESKTOP).
SHF_STARTMENU | 11 | The path to the user's Start Menu folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.
SHF_STARTMENU_COMMON | 22 | The path to the user's Start Menu folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this will simply be the path to the user's Start Menu folder (same as SHF_STARTMENU).
SHF_STARTMENUPROGRAMS | 2 | The path to the Programs folder in the user's Start menu. On Windows NT/2000/XP/Vista or later, 98/ME this is the path from the per-user profile.
SHF_STARTMENUPROGRAMS_COMMON | 23 | The path to the Programs folder in the user's Start menu. On Windows NT/2000/XP/Vista or later, 98/ME, this is the path from the All Users profile. On Windows 95, this will simply be the path to the Programs folder in the user's Start menu (same as SHF_STARTMENUPROGRAMS).
SHF_STARTUP | 7 | The path to the user's Startup folder. On Windows NT/2000/XP/Vista or later, 98 /ME, this is the path from the per-user profile.
SHF_STARTUP_COMMON | 24 | The path to the user's Startup folder. On Windows NT/2000/XP/Vista or later, 98/ ME, this is the path from the All Users profile. On Windows 95, this will be the path to the user's Startup folder (same as SHF_STARTUP).
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 2000/XP, and "C:\My Documents" on Windows 98/ME 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. On Windows NT/2000/XP, this is the path from the per-user profile. 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 NT/2000/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 Application Data folder on the user's system. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this will be the path to the user's Application Data folder (same as SHF_APPLICATIONDATA)

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\\Visual Patch X.X\\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

Windows 2000

Windows NT 4

Windows NT 3

Windows ME

Windows 98

Windows 95

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 (Windows 95, 98, ME) and "2" if the OS is NT based (Windows NT 4, 2000, 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, Windows 2000 Professional, or Windows NT Workstation 4.0 SP6 and later.
Server: Windows Server 10, Windows Server 2012 R2, Windows Server 2012, Windows Server 2008 R2, Windows Server 2008, Windows Server "Longhorn", Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0 SP6 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, Windows XP Home Edition, Windows 2000 Professional, or Windows NT 4.0 Workstation. 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, Windows Server 2003, Datacenter Edition or Windows 2000 Datacenter Server 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 2008 Enterprise Edition, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server, or Windows NT 4.0 Enterprise Edition, 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 are 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 Server 2003 R2. 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 NT/2000/XP/Vista or later with administrator permissions. True will be returned if the user has administrator permissions and false if they do not. On non-NT operating systems, true will always be returned. 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 Patching On Windows Vista 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 or later operating systems, the result will be the same as the normal administrator check IsAdmin as mentioned above.

Note: See Patching 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.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.

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.

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. 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.


VisualPatch.CheckFolderVersion

string VisualPatch.CheckFolderVersion (

string SessionVariable,

string Folder )

Description

Checks to see what version of your software is located in the target folder and returns its version number (name on the version tab).

This action looks through all releases in the project, starting with the newest release, and does the following:

  • Finds key files in that release that have SessionVariable in them.

  • The key files will be looked for to see if they all exist in the Folder. If all key files that match the SessionVariable folder pattern exist and have the correct MD5 value, the action will return the version number (version tab name), otherwise it will return nil.

Parameters

SessionVariable

(string) The name of the session variable to search for in each key file's destination paths, for example %AppFolder%.

Folder

(string) The path to the folder that you want to check.

Returns

(string) The version number (version tab name) whose key files containing the SessionVariable pattern were found in the specified Folder that also have the correct MD5 value. If the key files cannot be located, 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.


VisualPatch.GetLocalizedString

string VisualPatch.GetLocalizedString (

string StringID )

Description

Gets the localized text (based on current patch language) of the global (opposed to per-screen) strings.

Note: These are the strings defined in ...\Visual Patch 3.0\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.


VisualPatch.GetTargetVersion

string VisualPatch.GetTargetVersion (

)

Description

Gets the name of the target (newest) version in the patch. This is the version that is being patched to.

Parameters

None.

Returns

(string) The name of the target version in the patch (the name or version number on the newest version tab in your project). 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.


VisualPatch.SetLocalizedString

VisualPatch.SetLocalizedString (

string StringID,

string Text )

Description

Sets the text of a string ID in the current language for the patch.

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.


VisualPatch.WriteToLogFile

VisualPatch.WriteToLogFile (

string Text,

boolean AddTimestamp = true )

Description

Writes a string of text to the patch 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 patch, 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/2005 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.


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 Visual Patch 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 Visual Patch:

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

(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."

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."

2861

"Invalid table data."

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."

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

"This 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 not 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."


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 Visual Patch. The first type are called Global variables that are expanded once at the beginning of the patch. 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 patching 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 patch 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 Visual Patch:

_CommandLineArgs

A numerically indexed table that contains the command line arguments passed into the patch executable.

_DesktopFolder

The path to the user's Desktop folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.

_DesktopFolderCommon

The path to the user's Desktop folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this will simply be the path to the user's Desktop folder (the same as _DesktopFolder).

_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.

_PatchStages

A table of Boolean values that control whether certain patch stages are executed at runtime. Initially these values are set to true. If you want to skip a future patch stage, you can set its table entry to false. The patch stage table contains the following indexes that can be set:

"RunOnStartupActions"
"ShowBeforePatchingScreens"
"RunOnPrePatchActions"
"ShowWhilePatchingScreen"
"PatchFiles"
"RemoveLegacyFiles"
"RunOnPostPatchActions"
"ShowAfterPatchingScreens"
"RunOnShutdownActions"

Note: These values simply control whether or not the "stage" will be executed. This feature is mainly used for skipping stages.

_IR_ProductID

This variable contains the string "VP30" when used in Visual Patch. 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 patch in order to replace files that were in use. This variable is initially set to false when the patch starts and is set to true if the system needs to be restarted.

Note: If the patch 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 _Global_Functions.lua.

_ProgramFilesFolder

The user's Program Files folder (typically, this is something like "C:\Program Files").

_SilentPatch

Whether or not the patch should be run in "silent mode". Initially this value is set to the boolean value false, but if set to true the patch 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 _SilentPatch at any time, you should only switch to or from silent mode on one of the four "main" action tabs:

On Startup

On Pre Patch

On Post Patch

On Shutdown

Changing the value of _SilentPatch 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 patch executable was run from (e.g. "C:" or "D:").

_SourceFilename

The full path and filename of the patch executable (e.g. "C:\Downloads\patch.exe").

_SourceFolder

The full path to the folder that the patch executable was run from (e.g. "C:\Downloads" or "D:\").

_SystemFolder

The path to the user’s Windows System folder (e.g. "C:\Windows\System" on non-NT systems and "System32" on NT based systems).

_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 Visual Patch extracts the files it will need for the patch. (For example, this is the directory where Primer files are extracted to.)

Usually this directory will be a subfolder of the user's temporary directory, unless overridden with the /T command line option.

_UseSystemCharacterSet

If set to true, Visual Patch 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 Visual Patch'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 patch. 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.

Tip: The pre-defined session variables are listed along with all of the actions and constants when you press Ctrl+Space in the action editor. Since all of the session variables start with an percentage character "%", if you type % and then press Ctrl+Space, you'll be taken right to the first session variable in the list.

The following pre-defined session variables are available in Visual Patch:

%AppFolder%

The main directory where your application has been located given the specified key files. A folder can be determined as the application folder using the VisualPatch.CheckFolderVersion and VisualPatch.GetTargetVersion actions. This folder path is set through action script generated by you, or automatically generated for you when you use the project wizard.

%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-user 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."

%CommonFilesFolder%

The user's Common Files folder. Typically, this is something like: C:\Program Files\Common Files.

%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.

%DesktopFolder%

The path to the user's Desktop folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.

%DesktopFolderCommon%

The path to the user's Desktop folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this will simply be the path to the user's Desktop folder (the same as _DesktopFolder).

%FontsFolder%

The path to the user’s font directory (e.g. "C:\Windows\Fonts").

%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 2000/XP and "C:\My Documents" on Windows 98/ME, and "C:\Users\YourName\Documents" on Windows Vista or later.

Note: Windows 95 did not have the My Documents folder and this variable will return "C:" if run on such a system.

%ProductName%

The name of the product that you are patching. 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").

%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 patch executable was run from (e.g. "C:" or "D:").

%SourceFolder%

The full path to the folder that the patch executable was run from (e.g. "C:\Downloads" or "D:\").

%SourceFilename%

The full path, including the filename, for the current patch executable.

For example, if the user was running "patch.exe" from "C:\Downloads", %SourceFilename% would be expanded to "C:\Downloads\patch.exe".

%StartFolder%

The path to the user's Start menu folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.

%StartFolderCommon%

The path to the user's Start menu folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this will simply be the path to the user's Start menu folder (the same as %StartFolder%).

%StartProgramsFolder%

The path to the Programs folder in the user's Start menu. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.

%StartProgramsFolderCommon%

The path to the Programs folder in the user's Start menu. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this will simply be the path to the Programs folder in the user's Start menu (the same as %StartProgramsFolder%).

%StartupFolder%

The path to the user's Startup folder. On Windows NT/2000/XP/Vista or later, this is the path from the per-user profile.

%StartupFolderCommon%

The path to the user's Startup folder. On Windows NT/2000/XP/Vista or later, this is the path from the All Users profile. On a non-Windows NT system, this will be the path to the user's Startup folder (the same as %StartupFolder%).

%SystemFolder%

The path to the user’s Windows System folder (e.g. "C:\Windows\System").

%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 Visual Patch extracts the files it will need for the patch. (For example, this is the directory where Primer files are extracted to.)

Usually this directory will be a subfolder of the user's temporary directory, unless overridden 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 patch 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 by choosing Publish > Settings... from the program menu and selecting the Constants tab.

The following design-time constants are available in Visual Patch:

#ASC????#

This is a special set of design-time constants. When a constant's name starts with "#ASC", Visual Patch interprets the value assigned to that constant as the ASCII value of a character. Wherever you use that constant, Visual Patch 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, Visual Patch 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 patch executable is built.

#CURRENTHOUR#

A number representing the current hour in 24-hour time (e.g. 4:00 PM is 16), calculated when the patch executable is built.

#CURRENTMINUTE#

The current minute, calculated when the patch 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 patch 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 patch executable is built. January is represented by "01" and December is represented by "12".

#CURRENTSECOND#

The current second, calculated when the patch 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 patch executable is built.

#DATE#

The current date on your development system when the patch executable is built. It's in the format MM/DD/YY. So, if you built the patch on April 23, 2005, #DATE# would be "04/23/05".

#EUROPEANDATE#

The current date on your development system when the patch executable is built, in the European dating format: DD/MM/YY. For example, if you built the patch on April 23, 2005, #EUROPEANDATE# would be "23/04/05".

#ISODATE#

The current date on your development system when the patch executable is built, in the ISO format: YYYY-MM-DD. For example, if you built the patch on April 23, 2005, #ISODATE# would be "2005-04-23".

#JULIANDATE#

The current date on your development system when the patch 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 built-in variable %JulianDate% to build patches that expire a certain number of days after they are created. To calculate the number of days that have elapsed since the patch executable was generated, use the formula %JulianDate% - #JULIANDATE#.

#NEWESTVERSION#

The name of the newest version in your current build. This value is dynamically defined at build time.

#OLDESTVERSION#

The name of the oldest version in your current build. This value is dynamically defined at build time.

#PROGRAMFILESDIR#

The path to the Program Files directory on your development system.

#PROJECTFILEDIR#

This is the path to the Visual Patch project (.VP2) 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 (.VP2) file and the files in your patch 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.

#VPDIR#

The path to the directory where Visual Patch is installed on your development system. Usually this will be "C:\Program Files\Visual Patch 3.0".

#SYSDIR#

The path to the system directory on your development system.

#VERSIONTABNAME#

This constant expands to the name of the current version tab. It should only be used in the file properties area and will not expand in any other areas of the program.

#WINDIR#

The path to the Windows directory on your development system.


File Menu

File Menu Commands

Overview

New Project

Starts a new Visual Patch project using the project wizard. 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 Visual Patch project file. Visual Patch projects have the ".vp2" file extension. You can also access this menu item using Ctrl+O.

Note: You can also open Visual Patch 1.0 projects (*.vp1) using this menu option. See the Importing Visual Patch 1.0 Projects topic for details.

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 16 most recently viewed Visual Patch projects.

Exit

Closes the current project and exits out of Visual Patch. If there are any unsaved changes in the current project, you will be prompted to save them.


Project Wizard - Overview

Project Wizard

Overview Contents

The Project Wizard is a user friendly means of creating a new project. The wizard allows you to specify your personal/company information, define your versions and version file lists along with key files, choose a theme for your patch, and configure a handful of other features. The project wizard can be used to create a simple, fully functioning patch, with no further configuration from you.

To access the Project Wizard, choose File > New from the program menu.

The project wizard contains a series of pages that are shown to allow you to make choices and collect information. See the Contents topic for a list of the project wizard pages you may encounter when creating a new project.

Note: You can optionally disable the Project Wizard from displaying whenever a new project is created by checking the Stop showing Project Wizard option from within the Project Wizard, or from the document preferences dialog. You can access the program preferences by choosing Edit > Preferences from the program menu if you wish to re-enable the Project Wizard.


Contents

Project Wizard

Overview Contents

Below is a list of the pages you may encounter while creating a new project through the Project Wizard:

  • General Information

  • User Interface

  • Window Settings

  • Theme

  • Define Versions

  • Locate Installed Version

  • Registry Location

  • File Search

  • Optional Features


General Information

Project Wizard

Overview General Information

The General Information page is the first page of the Project Wizard that allows you to configure your product and company information.

Visual Patch Project Wizard

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 Visual Patch. This value will be stored in the session variable %ProductName%.

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%.

Next

Proceed to the next project wizard page, User Interface.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and the standard template will be created.


User Interface

Project Wizard

Contents User Interface

Visual Patch has the flexibility to use one of several different types of interfaces for the patch. Whether you prefer a full wizard screen, a minimalist dialog approach, or a silent patch with no visual interface at all, Visual Patch can handle each situation with ease.

Interface Type

Wizard style

Use a full wizard style interface for the patch. A wizard style interface consists of Visual Patch screens.

Dialog style

Use dialogs for the interface of the patch.

Silent

Don't show any user interface while the patch is running.

Back

Go back to the General Information page.

Next

The next project wizard page is based on the interface type selected. It will be one of the following pages:

Window Settings
Define Versions

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and the standard template will be created.


Window Settings

Project Wizard

Contents Window Settings

This project wizard page contains the style of the wizard window providing the ability to add a background window to your patch. You can add a background window later by choosing Project > Settings... from the program menu and selecting the Background tab.

Window Style

Wizard

Configures your patch to run as a wizard style application, much the same as the Project Wizard.

Wizard with background window

Configures your patch 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 tile across the background window. You can either type in the path manually, or click the Browse button.

Back

Go back to the User Interface page.

Next

Proceed to the next project wizard page, Theme.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and the standard template will be created.


Theme

Project Wizard

Contents Theme

Visual Patch 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 by choosing Project > Settings... from the program menu and selecting the Theme tab.

Select a project theme:

The project theme that your patch will use. You can click the select button to show the available project themes. An example screen with the chosen theme will be shown in the area below the selection.

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.

Back

Go back to the Window Settings project wizard page.

Next

Proceed to the next project wizard page, Define Versions.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and the standard template will be created.


Define Versions

Project Wizard

Contents Define Versions

The Define Versions page of the project wizard allows you to configure what versions of your application will be part of the patch and which files belong to each of those versions.

Software Versions

A list of the versions that will be created in your project. The first item in the list should be the first (oldest) version of your application and the last item in the list should be the last (current) version of your application.

Version

The names of each version that will be created in your project.

Source Folder

The paths to the folders where each version's files can be found.

Key File

The paths to the chosen key files for each version.

Add

Opens the Version Properties dialog where you can add new versions to the version list.

Remove

Remove the selected software version from the version list.

Edit

Opens the Version Properties dialog where you can edit the properties of the selected version.

Up

Move the selected version up one position in the version list.

Down

Move the selected version down one position in the version list.

Back

Go back to the previous project wizard page.

Next

Proceed to the next project wizard page, Locate Installed Version.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and the standard template will be created.


Project Wizard

Contents Locate Installed Version

In order for Visual Patch to be able to patch your application, it needs to know what version is currently on the user's system and what folder those application files are in. This page provides a few options that are available for locating the application folder.

Locate Installed Version

Current folder

Check to see if the folder that the patch is run from is the application folder.

Registry key

Read the application's folder location from a Registry value that was stored there previously.

File search

Search the user's system for a particular file that you know will exist in the application folder.

Back

Go back to the previous project wizard page.

Next

The next project wizard page is based on the interface type selected. It will be one of the following pages:

Registry Location
File Search
Optional Features

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and the standard template will be created.


Registry Location

Project Wizard

Contents Registry Location

Most applications store the application folder path in the Registry when it is installed. These settings are used to configure the Registry location that this value can be read from.

Read Folder from Registry

Main key:

The main or "root" key containing the Sub key.

Sub key:

The sub key containing the Value.

Value:

The name of the sub key value where the application folder path is stored.

Back

Go back to the Locate Installed Version project wizard page.

Next

The next project wizard page is based on the Locate Installed Version settings selected. It will be one of the following pages:

File Search
Optional Features

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and the standard template will be created.


Project Wizard

Contents File Search

This project wizard page allows you to search the user's system for a specific file located in the application folder. This allows Visual Patch to determine which version is currently installed. The search will stop when Visual Patch finds the file and confirms that the folder is the application folder given the specified key files for each version.

File Search

Search for file:

The name of the file that you want to search for that is located in the application folder.

Folders to search:

A list of the folders to search for the file specified in the Search for file field above. Each folder path must be on a separate line.

Tip: You can use built-in Session Variables to form paths to common directories.

If not located in the above folders:

If the file being searched for is not in one of the specified folders, perform a system search. Choose from:

Search all fixed (hard) drives

Search all fixed hard drives for the file.

Search all network drives

Search all network drives for the file.

Back

Go back to the previous project wizard page.

Next

Proceed to the next project wizard page, Optional Features.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and the standard template will be created.


Optional Features

Project Wizard

Contents Optional Features

This page is the final page of the project wizard and where you can configure some optional features for your patch.

Project Options

Create a log file while patching

Whether to create a log file while the patch is running. This setting can be enabled later by choosing Project > Settings... from the program menu and selecting the Advanced tab.

Warn the user if they don't have Administrative privileges

If checked, and the patch is run on a system without administrative privileges, the user is alerted, and the patch will 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.

Backup patched files

Create backups of all existing files that are being patched before overwriting them and store them in a backup folder. Each existing file being patched will be renamed to filename.bak. If filename.bak already exists, it will be named filename.bk1, or filename.bk2, etc.

You can find this setting by choosing Project > Settings... from the program menu and selecting the Advanced tab.

Enable file rollback support

Make the patch rollback the already patched files to their original state if an error occurs during the patching stage, or if the user aborts the patching stage by clicking the Cancel button. The "patching stage" is the stage when the files are actually being patched on the user's system. No rollback is performed if the user cancels before or after this stage.

If the Backup patched files option is selected, the rollback will use the backed up files from the backup folder. If the Backup patched files option is not selected, the patched files will be backed up to a unique folder in the user's Temp folder.

You can find this setting by choosing Project > Settings... from the program menu and selecting the Advanced tab.

Require the user to close your software before patching

Require that the software must be closed before proceeding with the patch. If it is running, the user will be prompted to close it.

Filename:

The filename of the program executable that must be closed.

Program name:

The name of the program as it appears in the program's title bar.

Back

Go back to the previous project wizard page.

Finish

Create your new project!

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and the standard template will be created.


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 Visual Patch 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 Visual Patch 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.


Edit Menu

Edit Menu Commands

Overview

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 version tab 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 version tab or another project. You can also access this menu item using Ctrl+C.

Paste

Pastes one or more files or folder references from the Windows clipboard to a version tab. You can also access this menu item using Ctrl+V.

Delete

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.

Select All

Selects all of the files and folder references on the current version 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 version 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 Visual Patch design environment to suit your style.


Preferences - Overview

Preferences

Overview Build Memory 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 Visual Patch design environment to your liking.

To access the Preferences dialog, choose Edit > Preferences... from the program menu.

There are 12 categories on the Preferences dialog:

  • Build

  • Memory

  • Code Signing

  • Document

  • Adding Files

  • Languages

  • Environment

  • Folders

  • Script Editor

  • Spell Checker

  • Startup

  • Updates


Build Preferences

Preferences

Overview Build Memory Code Signing Document Environment Script Editor Spell Checker Startup Updates

You can use these settings to control how Visual Patch builds a project. To view and change any build options, use the Build Settings dialog (Publish > Settings...).

General

Build with Publish Wizard

If selected, Visual Patch will use the Publish Wizard when building. If not selected, it will build using the settings specified in Build Settings.

Open output folder after build

Make Visual Patch open the output folder by default after a build has completed.

Confirm before building (non-Wizard mode only)

If selected, Visual Patch will confirm the build process before continuing. If unselected, it will build the project as soon as build is selected.

Note: This setting has no effect when the Publish Wizard is used.

Show low memory warnings

Make Visual Patch show low memory warnings when building the patch. These warnings are determined based on the largest file that will be differenced during the build process. There are two cases when a warning may be shown:

  • If the total system memory may not be sufficient to produce an optimal patch for one of your files. It is possible that increasing the system memory may result in a slightly smaller patch file for this project.

  • If there may not be enough free memory to complete the build process as quickly as possible. In this case, it is recommended that you close all other programs before starting the build process.

Verbose log output (include individual file items)

If selected, individual files are listed in the build output.

Tip: Turning verbose logging off can prevent "Out of memory" errors in projects with large amounts of files.

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.

Log Files

None

Do not save the build log file each time a build is performed.

Save in output folder

Save the build log file to the patch output folder as defined on the Build Settings dialog.

Save in other folder:

Save the build log file in a custom folder. You can click the Browse button to select a folder on your system.


Memory Preferences

Preferences

Overview Build Memory Code Signing Document Environment Script Editor Spell Checker Startup Updates

The following memory settings only apply to the differencing engine in Visual Patch and do not apply to Visual Patch's interface requirements. For example, setting the max virtual memory to 512 MB will mean the differencing engine won't use more than 512 MB, however the total memory used by Visual Patch might go beyond 512 MB due to features like the file lists and the build output log.

Note: The amount of memory used by the differencing engine depends on the size of the largest file in your project. (The number of files in your project does not matter.)

Tip: If you get an "Out of Memory" error with plenty of memory free, it is most likely due to the number of files in your project. If your project contains thousands of files, try turning off verbose logging in the Build preferences to prevent the build output from growing too long.

Maximum Virtual Memory to Allocate

Percentage of total physical memory to allocate

The maximum virtual memory to allocate, as a percentage of total physical memory. (1-100)

Megabytes to allocate

The maximum virtual memory to allocate, in megabytes.

Minimum Free Memory

The minimum physical memory to leave free, in megabytes.


Code Signing Preferences

Preferences

Overview Build Memory 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.

CodeSign patches

Code sign all new patches during the build process.

Code signing tool:

The tool you want to use to digitally sign all new patch projects. Choose from:

SignTool.exe

Use SignTool.exe to digitally sign the patch file. This tool could not be distributed, but is available in the \Bin folder of the Platform Software Development Kit (SDK). This tool is not supported on Windows NT/Me/98/95. For more information, see MSDN: SignTool (Windows).

SignCode.exe

Use SignCode.exe to digitally sign the patch 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 patches. 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.

Private key filename:

The full path and filename of the "Private Key" file (*.pvk) to use for signing all new project patches. 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 patches, such as: http://timestamp.verisign.com/scripts/timstamp.dll. If you do not want to timestamp the patch 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. Visual Patch automatically passes the "sign" argument when "SignTool.exe" is the selected tool.


Document Preferences

Preferences

Overview Build Memory Code Signing Document Environment Script Editor Spell Checker Startup Updates

Auto-Save

Enabled

Make Visual Patch save your project automatically at regular intervals.

Interval:

The time in minutes to wait between autosaves. This is how long Visual Patch 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 Visual Patch 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.vp2

Undo/Redo

Levels

The maximum number of changes that will be undo-able in Visual Patch. (Set this to 0 to disable the undo/redo feature.)

Note: You can change how added files are handled by changing the Adding 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.


Adding Files Preferences

Preferences

Document Adding Files

On Drop Folder(s)

Add folder reference

If selected, any folders inserted into a Visual Patch project by dragging and dropping will be automatically inserted as folder references.

Add file reference

If selected, any folders inserted into a Visual Patch project by dragging and dropping will be automatically inserted as file references.

Ask

If selected, when any folders are inserted into a Visual Patch project by dragging and dropping, a dialog will be displayed asking if the folders should be added as folder references, or as file references.

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 list is refreshed.


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 Memory Code Signing Document Environment Script Editor Spell Checker Startup Updates

Colors

Missing files

Files listed in Visual Patch that cannot be found at the location referenced will be shown in this color. You can click the select button to bring up a color chooser.

Key files

All key files in the project will be shown in this color. You can click the select button to bring up a color chooser.

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 Visual Patch is on or off.


Folder Preferences

Preferences

Environment Folders

Temporary build files:

The full path to the folder where Visual Patch 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 ( [image] ) to select a new folder.

Default output folder:

The full path to the folder where Visual Patch will store the file(s) generated during the build process.

Preference files:

The full path to the location where Visual Patch will store its preferences files.

Additional themes:

A semi-colin delimited list of folder paths that you want Visual Patch to parse looking for additional project themes beyond the ones in the Themes folder of the program. For example, C:\MyProjectThemes;Z:\VPThemes. This allows you to store themes on a network drive that can be shared between products and developers.

If Visual Patch 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 Memory 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 Memory 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, vp2.

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.

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 ( [image] ) to select a custom dictionary file (*.dic). Additional dictionaries can be downloaded from Visual Patch's web site, www.visualpatch.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 Memory 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, opening an existing project, opening the last used project, or exiting Visual Patch.

Open last project

Automatically opens the last project used when Visual Patch is launched.

Start new project

Automatically start a new project when Visual Patch is launched.


Updates Preferences

Preferences

Overview Build Memory Code Signing Document Environment Script Editor Spell Checker Startup Updates

Auto-Update

Enabled

Whether to automatically check for new versions of the Visual Patch 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 Visual Patch.

Frequency

How often (the number of days) you want Visual Patch to check for an update.

Silent until update available

Only show the update interface if an update is available.

Connection Properties

Open the Connections tab of Internet Explorer's Internet Properties dialog where you can configure the connection settings that Visual Patch will use when it checks for updates. These are the same settings that Internet Explorer uses.


Versions Menu

Versions Menu Commands

Overview

Add...

Add a new version tab to your project. This opens the New Version dialog where you can specify the version's name.

Remove

Remove the selected version tab from your project. A confirmation dialog will be shown before the tab's deletion.

Rename...

Rename the selected version tab. This opens the Rename Version dialog where you can specify its new name.

Duplicate

Make a duplicate copy of the selected version tab and its contents, and add it to your project. After the version tab has been duplicated and added to your project, you can rename it using the Rename option on this menu.

Organize...

Opens the Organize Versions dialog where you can change the order of your version tabs.

Note: You must have at least two version tabs in order to use this feature.

Add Files...

Opens the Add Files to Project dialog that you can use to add new files to your Visual Patch project. You can also access this menu item using the Insert key.

Note: When using the "All files in this folder" and "All files in this folder and all sub folders" options, you must be inside the target folder. It will not work if you simply highlight the target folder.

Tip: You can customize the file filters for adding files by editing a file called _add_files_filters.txt located in Visual Patch's "Data" folder.

Add 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.

Set Keyfile

Sets the key file property for the selected file(s). Key files are files unique to each version that are used to identify what version of the application is on the user's system.

Clear Keyfile

Deselects the key file property for the selected file(s).

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.


Organize Versions

Overview

The Organize Versions dialog allows you to organize the version tabs you have added to your project in order to keep track of your application versions and generate the proper binary differences during the build process.

Version tabs are ordered from left to right in the design environment where the leftmost version tab is the first version of your application and the rightmost version tab is the newest (current version) of your application.

The Organize Versions dialog is ordered from top to bottom where the first version in the list is the oldest version and the last version in the list is newest (current version).

Move Up

Move the selected version tab up one position in the version list.

Tip: You can also use the Ctrl+Up Arrow shortcut key.

Move Down

Move the selected version tab down one position in the version list.

Tip: You can also use the Ctrl+Down Arrow shortcut key.


Files - Overview

Files

Overview

While patches can be created to accomplish many different tasks, the patching of files is the main purpose of a patch. Visual Patch allows you to easily add, remove and edit the properties of files you want to patch on the end users system.

Once you have determined what files are part of each version of your project, you are ready to add them to your Visual Patch project.

Adding Files

Files can be added to each version of your project using one of the following methods:

  • From the program menu by choosing Versions > 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 Visual Patch 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 Edit > Delete.

  • 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 Visual Patch:

  • 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 Versions > 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 Conditions 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, key file property and patch conditions.

You can access the file properties dialog by selecting Versions > 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 three tabs:

  • General

  • Conditions

  • Notes


Single File Properties - General

File Properties

Overview General Conditions 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.

Key file

Whether or not the file is a key file. Key files are files unique to each version that are used to identify what version of the application is on the user's system.

Destination

Install to:

The directory that you want the file to be patched 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: Visual Patch 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.

Force install:

Whether or not to force Visual Patch to install the file. This means that if a file with the same name exists in the destination, it will be overwritten. If the file does not exist, it will install it.

Note: Checking this option means that the full copy of this file will be included in the patch.


Single File Properties - Conditions

File Properties

Overview General Conditions Notes

The Conditions tab is used to conditionally include/exclude a file from the patch 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 patch.

Operating Systems

The operating systems that the file will be patched 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 95

  • Windows 98

  • Windows ME

  • Windows NT 3.51

  • Windows NT 4.0

  • Windows 2000

  • Windows XP

  • 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 patched.

Some examples of valid conditions are:

my_variable > 10

This means if the numeric value of the variable "my_variable" is greater than 10, patch the file. If the value is less than 10, do not patch the file.

my_variable == "Custom"

This means if the string value of the variable "my_variable" equals the string "Custom", patch the file. If the strings are not equal, do not patch the file.


Single File Properties - Notes

File Properties

Overview General Conditions Notes

Notes:

A private field used to store information about the current file. These notes are not included in the final build of the patch and are only available in the Visual Patch design environment.


Multiple File Properties - Overview

Multiple File Properties

Overview General Conditions

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, key file property and their patch conditions.

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 Versions > 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 two tabs:

  • General

  • Conditions


Multiple File Properties - General

Multiple File Properties

Overview General Conditions

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.

Key file

Whether or not the selected files are key files. Key files are files unique to each version that are used to identify what version of the application is on the user's system.

Destination

Install to:

The edit state of the directory that you want the selected files to be patched 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 patch folder for all selected files.

Note: Visual Patch 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.

Force install:

Whether or not to force Visual Patch to install the selected files. This means that if a file with the same name exists in the destinations, they will be overwritten. If the files do not exist, they will be installed.

Note: Checking this option means that the full copy of these files will be included in the patch.


Multiple File Properties - Conditions

Multiple File Properties

Overview General Conditions

The Conditions tab is used to conditionally include/exclude the selected files from the patch 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 patched 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 95

  • Windows 98

  • Windows ME

  • Windows NT 3.51

  • Windows NT 4.0

  • Windows 2000

  • Windows XP

  • 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 patched.

Some examples of valid conditions are:

my_variable > 10

This means if the numeric value of the variable "my_variable" is greater than 10, patch the file. If the value is less than 10, the file will not be patched.

my_variable == "Custom"

This means if the string value of the varibale "my_variable" equals the string "Custom", patch the file. If the strings are not equal, the file will not be patched.


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 patch periodically. When updating the patch, 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 patch up-to-date whenever you build.

Instead of adding individual files to your patch one by one, you can specify entire folders to include. This is accomplished by adding a folder reference to your patch 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.

Adding Folder References

Folder references can be added to your project using one of the following methods:

  • From the program menu by choosing Versions > Add 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 Visual Patch 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 Edit > Delete.

  • 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 Visual Patch:

  • 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 Versions > 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 Conditions 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 Versions > File 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.

The folder reference properties dialog contains the following three tabs:

  • General

  • Conditions

  • Notes


Single Folder Reference Properties - General

Folder Reference Properties

Overview General Conditions Notes

Source

Local folder:

The location of the folder on your development system whose contents you want to include in the patch. 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.

File mask:

The file mask you want to use to determine which files will be included or excluded from the patch 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.

Destination

Install to:

The location that you want the folder's contents to be patched 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: Visual Patch 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.


Single Folder Reference Properties - Conditions

Folder Reference Properties

Overview General Conditions Notes

The Conditions tab is used to conditionally include/exclude a folder reference from the patch 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 patch.

Operating Systems

The operating systems that the folder's contents will be patched 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 95

  • Windows 98

  • Windows ME

  • Windows NT 3.51

  • Windows NT 4.0

  • Windows 2000

  • Windows XP

  • 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 Conditions

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 patched.

Some examples of valid conditions are:

my_variable > 10

This means if the numeric value of the variable "my_variable" is greater than 10, patch the files. If the value is less than 10, the files will not be patched.

my_variable == "Custom"

This means if the string value of the variable "my_variable" equals the string "Custom", patch the files. If the strings are not equal, the files will not be patched.


Single Folder Reference Properties - Notes

Folder Reference Properties

Overview General Conditions 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 patch and are only available in the Visual Patch design environment.


Multiple Folder Reference Properties - Overview

Multiple Folder Reference Properties

Overview General Conditions

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, destination and patch conditions.

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 Versions > File Properties... from the program menu.

Note: If you have only one folder reference selected when you select Folder Reference Properties, the Single Folder Properties dialog is displayed instead.

The multiple folder reference properties dialog contains the following two tabs:

  • General

  • Conditions


Multiple Folder Reference Properties - General

Multiple Folder Reference Properties

Overview General Conditions

Source

Local folder:

The edit state of the location of the folders on your development system whose contents you want to include in the patch. 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 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.

File mask:

The file mask state that will be used to determine which files will be included or excluded from the patch 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.

Destination

Install to:

The edit state of the location that you want each folder and its contents to be patched 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: Visual Patch 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.


Multiple Folder Reference Properties - Conditions

Multiple Folder Reference Properties

Overview General Conditions

The Conditions tab is used to conditionally include/exclude the selected folder references from the patch 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 patched 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 95

  • Windows 98

  • Windows ME

  • Windows NT 3.51

  • Windows NT 4.0

  • Windows 2000

  • Windows XP

  • 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 patched.

Some examples of valid conditions are:

my_variable > 10

This means if the numeric value of the variable "my_variable" is greater than 10, patch the file. If the value is less than 10, the file will not be patched.

my_variable == "Custom"

This means if the string value of the varibale "my_variable" equals the string "Custom", patch the file. If the strings are not equal, the file will not be patched.


Project Menu

Project Menu Commands

Overview

Settings...

Opens the Project Settings dialog where you can configure settings such as Session Variables, project theme, background and various advanced settings.

Resources...

Opens the Resources dialog where you can find project resources such as Primer Files, Global Functions, Includes and Plugins.

Screens...

Opens the Screens dialog where you can specify and manage what screens you would like to display during your patch.

Actions...

Opens the Actions dialog where you can create any actions that are needed during your patch. These actions would be created on the project events.

Languages...

Opens the Languages dialog where you can define what languages you want to support in your patch.


Project Settings - Overview

Project Settings

Overview Session Variables Theme Background Advanced

The Project Settings dialog is where you can configure various patch settings for your project. One section allows you to define a series of built-in and custom session variables for your patch. These are used as dynamic placeholders for commonly used values such as destination paths and product names.

Another category of settings found here is the project theme settings. Project themes are a set of visual attributes that are applied to all of the screens in your patch to give them a uniform look and feel. These attributes include the color, banner styles, images, text fonts and many more.

The third category of settings apply to the background window of your patch. The background window is a large window that your main patch window will sit on at runtime. The background window may be a solid color, gradient color, or even an image.

The Advanced section contains a few advanced settings for your patch such as backup options, rollback support, legacy file deletion, silent mode switches, advanced icon and taskbar representations, and log file generation settings.

Each of these categories can be accessed by selecting Project > Settings... from the program menu.

The Project Settings dialog contains the following four categories:

  • Session Variables

  • Theme

  • Background

  • Advanced


Session Variables

Project Settings

Overview Session Variables Theme Background Advanced

The Session Variables tab is where you can set general information and defaults about your product such as your product name, company name, product version and so on. These values are automatically assigned to built-in session variables that you can use throughout your project. 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, "Visual Patch".

%CompanyName%

The name of your company. For example, "Indigo Rose Software".

%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 patch is running.

Custom

A list of all of the currently defined custom session variables that are available in your patch.

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.


Theme

Project Settings

Overview Session Variables Theme Background Advanced

Project themes are a set of visual attributes that are applied to all of the screens in your patch 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 patch. These themes are stored globally and can be used for all of your projects.

Tip: Themes are very much like "skins" for your patch. 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. no banner

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\Visual Patch\3.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 Visual Patch 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 Visual Patch theme.


Background

Project Settings

Overview Session Variables Theme Background Advanced

The background window is a large window that your main patch 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 patch.

Show background window

Show a background window behind the main patch 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:

*.apm; *.bmp; *.emf; *.gif; *.jpg; *.pcd; *.pcx; *.png; *.psd; *.tga; *.tif; *.wmf

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.


Advanced

Project Settings

Overview Session Variables Theme Background Advanced

Options

Backup patched files

Create backups of all existing files that are being patched before overwriting them and store them in the specified Backup folder. Each existing file being patched will be renamed to filename.bak. If filename.bak already exists, it will be named filename.bk1, or filename.bk2, etc.

Backup folder:

The folder on the user's system that each backed up file will be created in.

Enable file rollback support

Make the patch rollback the already patched files to their original state if an error occurs during the patching stage, or if the user aborts the patching stage by clicking the Cancel button. The "patching stage" is the stage when the files are actually being patched on the user's system. No rollback is performed if the user cancels before or after this stage.

If the Backup patched files option is selected, the rollback will use the backed up files from the Backup folder. If the Backup patched files option is not selected, the patched files will be backed up to a unique folder in the user's Temp folder.

Delete legacy files

Delete all legacy files on the user's system when patching. A file is considered to be a "legacy file" if it exists in an older version, but is not part of the current version (not in the current version's file list).

Application Settings

Use custom icon:

Display a custom icon in the top left corner of your patch window. It will also be used to represent the patch on the Windows task bar. Click the Browse button to open the Insert File Reference dialog 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 patch.

Hide taskbar icon

Hide the taskbar icon during the patch.

Always on top

Make the patch 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.

Enable silent mode

Enable the patch to be run in "silent mode" using the /S command line option. This means that there will be no user interaction required during the patching process. If you are performing silent patching, it is highly recommended that you use a log file during the patching process so that you can debug the patch 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 patch in "silent mode" by default. If unchecked, you can run your patch in silent mode using the command line option /S, for example C:\Output\patch.exe /S. Selecting this option sets the global variable _SilentPatch to true.

Log File

Create log file

Generate a log file during the patching process. The patch log file is in ASCII text format and provides information about what happened during the patching process, such as which files were patched, which programs were executed, what Registry changes were made, etc. This information can be extremely useful if you ever need to debug a patch 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: 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).

Requested User Privilege Level

This section specifies which requested execution level to include in the patch's application manifest for distribution on Windows Vista or later. Patches should generally always be built using the default "Require administrator" setting. Before changing this default setting, see Patching On Windows Vista or Later for important information concerning required changes to your patch, and feature limitations.

Note: Changing the application manifest to "Highest available" or "As invoker" is only supported on Windows 2000 or later in Visual Patch's design environment.

Note: For more information on the settings below and general Windows Vista or later information, see Patching On Windows Vista or Later.

As invoker

The patch 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 patch. 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 patch 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 patch requires to be run with the full access token of an administrator. Generally patches make changes to protected system locations that are typically writable to only by administrator users. This is the default setting for patches created with Visual Patch.


Resources - Overview

Resources

Overview Primer Files Global Functions Includes Plugins

Project Resources are those 'behind the scenes' items in your patch which allow it to function properly. These include any files that are required during the execution of the patch, any plugins utilized by your patch, and any globally declared functions and script files used.

  • Primer Files

  • Global Functions

  • Includes

  • Plugins


Primer Files

Resources

Overview Primer Files Global Functions Includes Plugins

The Primer Files tab is where you can edit the list of primer files that will be included in the patch executable. The files in this list will be extracted from the patch executable before the patching process begins so they can be used at the very start of the patching process, right after the user runs the patch executable.

Any files listed in the Primer files list will be extracted immediately to the patch executable's temporary directory when the patch 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 patch by using the following path: %TempLaunchFolder%\Checker.exe

To access the Primer Files dialog, choose Project > Resources... from the program menu and select the Primer Files tab.

Files to extract to %TempLaunchFolder% when the patch 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 patch 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.

Add

Opens the Primer File Properties dialog where you can add a new primer file to the patch.

Remove

Remove the currently selected primer file from the patch.

Edit

Opens the Primer File Properties dialog where you can edit the properties of the currently selected primer file.


Global Functions

Resources

Overview Primer Files Global Functions Includes Plugins

The Global Functions dialog is a convenient place to include any functions or variables that you want to make available throughout your patch. Any functions or variables that you add here will be available right after your patch 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 Project > Resources... from the program menu and select the Global Functions tab.

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 Visual Patch Registry actions.


Includes

Resources

Overview Primer Files Global Functions Includes Plugins

The Includes 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 patch at build time. This enables any code within them to be called anywhere during your patch.

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 Includes dialog, choose Project > Resources... from the program menu and select the Includes tab.

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 patch. 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 patch 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 patch.
Application.Exit(0);
end

Filename

The full path and filenames of the script files that will be added to your patch at build time.

Note: Visual Patch 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 _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 Visual Patch. All available script files can be found in the Scripts folder, normally located in C:\Program Files\Visual Patch 3.0\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.


Plugins

Resources

Overview Primer Files Global Functions Includes Plugins

Action plugins are actions that are external to the Visual Patch 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 on the Action Plugins dialog) for information on what features it adds and how to use them.

Note: Any action plugins that are located in Includes\Plugins within the Visual Patch program directory will be available through the design environment by choosing Project > Resources... from the program menu and selecting the Plugins tab.

Visual Patch ships with the Zip Actions Plugin and the Clipboard Actions Plugin, however there are many others that can be integrated into your patches. Some examples of these include:

  • XML Plugin

  • SQLite Database Plugin

  • Cryptographic Actions Plugin

All available plugins can be found on the Indigo Rose Website or by clicking the More Plugins button on this dialog.

Available action plugins:

These are the available action plugins that can be added to your project. You can add an action plugin to your project by checking the box beside its title in the list.

More Plugins

Opens your default web browser to a location where you can find any additional action plugins that are available.

About Plugin

You can view information about any of the added plugins by first highlighting one, then clicking the About Plugin button. This will open the About Plugin dialog where you will find 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.

Plugin information:

A summary of information about the highlighted plugin such as its name, author and copyright. This information may vary between authors.


Screens - Overview

Screens

Overview Before Patching Progress After Patching

The Screens dialog is where you can add, remove, arrange, preview, export and configure all of the screens you want to show during the patching of your application.

Tip: You can also configure a project theme for your patch that you can apply to all of the screens without configuring each screen manually. You can configure the project theme by choosing Project > Settings... from the program menu and selecting the Theme tab. Themes are very much like "skins" for your patch. If you'd like to create your own themes, see Screen Dimensions and How Screens Are Drawn for some useful information.

The Screens dialog consists of the Before Patching, the Progress and the After Patching. These represent the three different times during the patching 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 patch. 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 three tabs can be found on the Screens dialog:

  • Before Patching

  • Progress

  • After Patching


Before Patching

Screens

Overview Before Patching Progress After Patching

The screens listed on the Before Patching tab will be shown before any files are patched on the user's system and before the optional progress screen on the Progress tab is shown. Each screen will be shown in sequential order, the first screen being shown right after the patch is launched.

Screens:

The screens that will appear after the patch starts, up until the point in which the files are going to be patched. The order that these screens appear in the list is the order that they will be shown at runtime.

Screen ID

The IDs of all of the currently added screens to be displayed before the files are patched.

Screen Type

The screen types of all of the currently added screens.

Preview:

An image preview of the selected screen.

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 Patching screen list.

Down ( )

Move the selected screen down one position in the Before Patching screen list.

Preview

Show a preview of the selected screen as it will appear during the execution of the patch.

Note: Some contents of the screen preview may not be accurate if it requires information that must be gathered during the patching process.

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.


Progress

Screens

Overview Before Patching Progress After Patching

The following settings are used to configure the style of progress you want to show while your application's files are being patched.

Progress Type

None

Don't display any visible progress during the patching of the files. If this option is selected, nothing will be shown during the patching process. This option is useful for silent patching.

Minimal

Display a dialog with a progress meter while the files are patched. This option is similar to the status dialog.

Progress screen

Display a progress screen during the patching of the files. You can click the Settings button to choose a screen and edit its properties.

Settings...

Opens the Progress Screens Properties dialog containing the While Patching tab where you can choose the type of progress screen to show, and edit its properties.


After Patching

Screens

Overview Before Patching Progress After Patching

The screens listed on the After Patching tab will follow the optional progress screen configured on the Progress tab. At this point, all files have been patched on 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 patched. The order that these screens appear in the list is the order that they will be shown at runtime.

Screen ID

The IDs of all of the currently added screens to be displayed after the files have been patched.

Screen Type

The screen types of all of the currently added screens.

Preview:

An image preview of the selected screen.

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 Patching screen list.

Down ( )

Move the selected screen down one position in the After Patching screen list.

Preview

Show a preview of the selected screen as it will appear during the patch.

Note: Some contents of the screen preview may not be accurate if it requires information that must be gathered during the execution of the patch.

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)

Note: The screen images used in this topic are from Indigo Rose's Setup Factory 7.0. The actual screens seen here may not be available in Visual Patch.

Table of Screen Dimensions and Coordinates

Here are the sizes and coordinates for the different parts of each screen in Visual Patch:

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

How screens are drawn

A typical screen being drawn (illustrations)

Using full-size banner images

Note: The screen images used in this topic are from Indigo Rose's Setup Factory 7.0. The actual screens seen here may not be available in Visual Patch.

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. 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

Visual Patch 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 patching needs beyond the standard scenario.

The following screen types are available in Visual Patch:

  • Buttons

  • Check Boxes

  • Combo Boxes

  • Custom

  • Edit Fields

  • License Agreement

  • List Box

  • Progress Bars

  • Radio Buttons

  • Scrolling Text

  • Scrolling Text Progress

  • Static Text


Overview

Buttons Screen

Overview Properties Advanced Examples

The Buttons screen is one type of screen available in Visual Patch 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 Patching or After Patching 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 project.

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 project 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 Visual Patch 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 Patching or After Patching 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 project.

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 patch. 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 Visual Patch. It was designed to allow you to present a selectable drop down to the user to make choices during the patch. 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 Patching or After Patching 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 project.

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 Visual Patch. 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 Patching or After Patching 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>.

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.

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 patch.

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 Visual Patch'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
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
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 Visual Patch. 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 Visual Patch, 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 Patching or After Patching tabs.

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 project.

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 patch. 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 Visual Patch. 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 patch. 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 Patching or After Patching 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 project.

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 project.

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 Patching or After Patching 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 project.

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 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 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 Visual Patch. It was designed to provide a visual representation of progress for various tasks during the patch. 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.

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 Patching or After Patching 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 Visual Patch 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 Visual Patch 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 project.

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 Patching" 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 Visual Patch 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 Patching or After Patching 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.

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 project.

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 Visual Patch. 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 Visual Patch. 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 Patching or After Patching tabs.

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 project.

Tip: You can also reference an external file at runtime using a session variable or hard-coded path.

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 project.

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 Visual Patch 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 Patching or After Patching tabs.

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 project.

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 Patching" 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

Static Text Screen

Overview Properties Advanced

The Static Text screen is one type of screen available in Visual Patch. 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 Visual Patch. One example is the Ready to Patch 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 Patching or After Patching tabs.

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 project.

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


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

Visual Patch'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 Visual Patch:

  • Button

  • Check Box

  • Combo Box

  • Edit Field

  • Group Box

  • List Box

  • Progress Bar

  • Radio Button

  • Scrolling Text

  • Static Text

  • Timer


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


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:

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 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 patch 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


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


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 Visual Patch.

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 patch.

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... from the program menu.


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:

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 (Action 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.

Show Whitespace

When selected, all spaces in the code window will be replaced visually with dots. When unselected, space characters are restored in the code view. This feature does not affect the functionality of the spaces in action script. It simply represents them in a visually different way.

Note: Blank lines are not considered white space unless there are space characters on those lines.

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 Visual Patch Registry actions.

Import...

Imports the contents of a script file (*.lua) into the code window.

Export...

Saves the current script in the code window as a script file (*.lua).

Print...

Prints the action script currently in the code window. You can also access this menu item using Ctrl+P.

Global Functions...

Opens a dialog where you can create any Global Functions you wish to include in your project.

Editor Settings...

Opens the action editor's Window Properties dialog where you can customize its settings.


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 patched to, or where it exists during the patch.

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 two categories of events in Visual Patch:

  • Project Events

  • Screen Events

Project Events

The following describes the four main project events that are fired at different points during the patch. You can access these events by choosing Project > Actions... from the program menu.

On Startup

This event is fired at the start of the patch, 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 Patch

This event is fired after all of the Before Patching screens have been shown and before the patching 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 Post Patch

This event is fired after all of the files have been patched - after the While Patching screen has been shown, but before the After Patching 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 patch, after all of the After Patching 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 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 patch, 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 patching files.

The following event variables are automatically set whenever this event is triggered:

e_Stage

(number) The progress stage that the patch is currently in. One of the following stages will be returned:

CONSTANT | VALUE | DESCRIPTION
PATCH_STAGE_PREPARING | 1 | The patch is preparing to patch the files.
PATCH_STAGE_PATCHING_FILES | 2 | The patch is in the process of patching the files.
PATCH_STAGE_REMOVING_LEGACY_FILES | 3 | The patch is removing legacy files 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 patch. For example, this text may contain the name of the current file that is being patched.

e_CurrentItemPct

(number) A value (between 1 and 100) that represents the percentage of the current process that has been completed. For example, when patching files, each file being patched will have it's own percentage value returned.

e_StagePct

(number) A value (between 1 and 100) that represents the percentage of the patch stage that has been completed so far. Possible patch stages can be found in the e_Stage table above.

On Start

This event is fired from a progress screen to start its progress actions.


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 patch's instructions in different languages based upon the language currently defined in their Operating System's Regional Settings.

Visual Patch 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 patch and what they would like to present to the user in those cases.

Language text is mainly used for messages generated throughout the patch, and on screens, both of which can be easily translated by the developer for multi-lingual patches.

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 ...\Visual Patch 3.0\Languages.

Screens can also be easily translated on a screen-by-screen basis, based on the languages that are currently supported by the patch. 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 patch. 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 patch:

A list of all of the languages that are currently supported by the Visual Patch project.

Language

The names of the languages currently added to the patch.

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 patch will use this language for its messages and screens.

Note: There can only be one default language per patch.

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 Visual Patch 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 patch.

Remove

Removes the currently selected language from your patch.

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 patch.

Set Default

Set the currently selected language to be "Default" language. This means that if the detected language is not supported by your patch, or if one of the supported languages does not have a message file associated with it, this language's message file will be used.

More Languages

Opens your default web browser to a web site where you can download additional language modules to use in your projects.


Publish Menu

Publish Menu Commands

Overview

Build

Opens the Publish Wizard to start 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.


Overview

Publish Wizard

Overview Output Versions Finished

The Publish Wizard is a user friendly means of building your patch. It allows you to see or configure the settings that will be used to generate your final patch executable.

Note: You can optionally disable the Publish Wizard from displaying whenever publishing your project by deselecting the Build with Publish Wizard option in the Build Preferences. You can access the program preferences by choosing Edit > Preferences... from the program menu.

You will encounter the following publish wizard pages when publishing your patch:

  • Output

  • Versions

  • Finished


Output

Publish Wizard

Overview Output Versions Finished

Each of the following options contain the settings that were configured on the Output tab of the Build Settings dialog. You can access the Build Settings dialog by choosing Publish > Settings... from the program menu.

Output Settings

Build patch to folder:

The directory that you want the patch executable saved to when it is finished building. You can click the Browse button to select an output folder.

Patch filename:

The name you want to give your patch file. This can be patch.exe, setup.exe or anything else that you want.

Next

Proceed to the next publish wizard page, Versions.

Cancel

Exit the publish wizard and ignore the changes made to any settings.


Versions

Publish Wizard

Overview Output Versions Finished

This publish wizard page allows you to define the versions you want to build into the patch. All available versions are listed top down from oldest to newest with checkboxes identifying whether or not the version will be built into the patch.

Back

Go back to the Output publish wizard page.

Build

Start the build process.

Cancel

Exit the publish wizard and ignore the changes made to any settings.


Finished

Publish Wizard

Overview Output Versions Finished

The Finished page is the final page of the project wizard. It shows a log of what was done during the build process and lists any errors that occurred.

Open output folder

Automatically open the output folder when the Finish button is clicked.

Build Log...

Automatically open the build log text file when the Finish button is clicked. The build log outlines what was done during the build process and is the same as what is shown in the log on this project wizard page, however it is saved by default to a text file in the output folder for future analysis.

Tip: You can turn off saving the log file or change its destination folder in the Build Preferences. The program preferences can be accessed by choosing Edit > Preferences... from the program menu.

Finish

Close the publish wizard and open the output folder (if that option was selected).


Build Settings - Overview

Build Settings

Overview Output Constants Code Signing Resources Pre/Post Build Optimizations

The Build Settings dialog is where you can make decisions that control the generation of your final patch executable. Some of these settings include: the location you wish to output the file; the build configuration you wish to use; the versions to build into the patch; design-time constants that you wish to recognize during the build process; the Code Sign settings to sign your patch; custom resource stamping; any programs you wish to run before or after the build process; and several optimization settings that can be used to increase build performance.

To access the Build Settings dialog, choose Publish > Settings from the program menu.

The Build Settings dialog contains the following six categories:

  • Output

  • Constants

  • Code Signing

  • Resources

  • Pre/Post Build

  • Optimizations


Output

Build Settings

Overview Output Constants Code Signing Resources Pre/Post Build Optimizations

Build configuration:

The build configuration you want to use when generating your final patch. The dropdown contains all of the current build configurations. A build configuration contains all previously saved information on the Output, Constants, Code Signing, Resources, and Pre/Post Build tabs.

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 patch executable saved to when it is finished building. You can click the Browse button to select an output folder.

Patch filename:

The name you want to give your patch file. This can be patch.exe, setup.exe or anything else that you want.

Encrypt patch archive data

Encrypt the files added to the patch's archive. Using this feature will increase the time to build the patch, and decompress the files at run time, however we recommend leaving this option enabled to keep your patch as secure as possible.

Versions to Build

The versions to build into the patch. All available versions are listed top down from oldest to newest with checkboxes identifying whether or not the version will be built into the patch.


Constants

Build Settings

Overview Output Constants Code Signing Resources Pre/Post Build Optimizations

Build configuration:

The build configuration you want to use when generating your final patch. The dropdown contains all of the current build configurations. A build configuration contains all previously saved information on the Output, Constants, Code Signing, Resources, and Pre/Post Build tabs.

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 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 the current build configuration.

Remove

Remove the selected design-time constant from the current build configuration.

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 Output Constants Code Signing Resources Pre/Post Build Optimizations

Tip: See the Code Signing section of the preferences (Edit > Preferences, Code Signing) to configure default values when creating new projects.

Tip: If you want full control over the how the patch 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, Visual Patch automatically passes the option "sign".

Build configuration:

The build configuration you want to use when generating your final patch. The dropdown contains all of the current build configurations. A build configuration contains all previously saved information on the Output, Constants, Code Signing, Resources, and Pre/Post Build tabs.

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.

CodeSign patches

If checked, the patch 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 patch. Choose from:

SignTool.exe

Use SignTool.exe to digitally sign the patch file. This tool could not be distributed, but is available in the \Bin folder of the Platform Software Development Kit (SDK). This tool is not supported on Windows NT/Me/98/95. For more information, see MSDN: SignTool (Windows).

SignCode.exe

Use SignCode.exe to digitally sign the patch 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 patch 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 patch 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. Visual Patch automatically passes the "sign" argument when "SignTool.exe" is the selected tool.


Resources

Build Settings

Overview Output Constants Code Signing Resources Pre/Post Build Optimizations

Build configuration:

The build configuration you want to use when generating your final patch. The dropdown contains all of the current build configurations. A build configuration contains all previously saved information on the Output, Constants, Code Signing, Resources, and Pre/Post Build tabs.

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

Note: This feature requires the patch to be built on Windows 2000 or greater.

Use custom icon

If checked, you can use a custom icon for the patch executable.

Path to local icon file:

The full path and filename of the icon file (.ico) to use for the patch executable. You can click the Browse button to select an icon file.

Custom Version Information

Note: This feature requires the patch to be built on Windows 2000 or greater.

Stamp executable with custom information

If checked, you can stamp the patch 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.

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 Output Constants Code Signing Resources Pre/Post Build Optimizations

Build configuration:

The build configuration you want to use when generating your final patch. The dropdown contains all of the current build configurations. A build configuration contains all previously saved information on the Output, Constants, Code Signing, Resources, and Pre/Post Build tabs.

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 patch executable is generated. You can click the Browse button to select the file you want to execute.

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 Visual Patch wait until after the program has finished running before it continues. If not checked, Visual Patch 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 patch executable is generated. You can click the Browse button to select the file you want to execute.

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 Visual Patch wait until after the program has finished running before it continues. If not checked, Visual Patch will simply start the program and continue without waiting.


Optimizations

Build Settings

Overview Output Constants Code Signing Resources Pre/Post Build Optimizations

Build Cache

Cache diff files

Make Visual Patch cache the project's diff files each time a build is performed. This means it will only ever make a diff between the same exact two files once. Once it is made and in the cache, the cached version will be used for future builds of diffs between those exact two files. This greatly decreases the build time if you are simply working on action script and not adding any further versions or files to your project.

Cache compressed file sizes

Make Visual Patch cache the compressed size of the files to speed up the build process. During the build, the program must calculate the compressed size of every diff file and target in order to produce optimal results. When this option is turned on, a database of compressed file sizes is kept. This can help speed up the build process, especially with large files.

Cache folder:

The folder to use to store the cached diffs and build data files. This folder can be used either as a per-project cache, or a shared cache for multiple projects. You can click the Browse button to select a folder.

Clear Cache

Deletes all cached files from the cache folder. It is a good idea to clear the build cache every once in a while, especially if the amount of free system memory you have available increases.

One reason for clearing the build cache is to free up disk space used by cache files. Another reason is that you may have more system memory available now than when you originally built the cache files and want to try to get better results on the next build.

Multipass Diff Creation

Enabled

If enabled, Visual Patch will perform multiple passes on each file in order to achieve the smallest possible diff size. Each successive pass will look for longer patterns in the file, which, depending on the internal structure of the file, may result in better compression.

If disabled, Visual Patch will use the default settings and will only perform one pass.

Initial pass time threshold:

The time threshold (in seconds) that will determine whether multiple passes should be performed on a file. If the first pass takes less time than this value, additional passes will be performed. If the first pass takes longer than this value, Visual Patch will not perform additional passes on the file.

You can use this setting to avoid performing the multipass optimization on files that take longer to build.

Note: If set to zero, the time threshold will be ignored and Visual Patch will always perform multiple passes.

Maximum additional passes:

The maximum number of additional attempts Visual Patch will use to create the smallest possible diff for each file. This can be a value between 1 and 10.

Low Memory Scenario

Minimize patch size

Use as much memory as necessary in order to achieve the smallest possible diff files.

Note: It is recommended that you select this option if you have the cache diff files option selected. When caching is enabled, the diff files will only need to be created once, so the amount of time it takes to create them is less important.

Maximize build speed

Maximize the speed of the build process when creating the patch. This will decrease compression, so you may not receive the smallest possible patch.


View Menu

View Menu Commands

Overview

Toolbars

Shows or hides the available toolbars.

Standard

Shows or hides the standard program toolbar.

Versions

Shows or hides the Versions toolbar.

Common

Shows or hides the common toolbar containing the most commonly used features.

Filters

Shows or hides the Filters toolbar.

Status Bar

Shows or hides the status bar at the bottom of the Visual Patch main screen.

Tasks

Shows or hides the Tasks panel.

Output

Shows or hides the Output panel.

Previous Tab

Selects the previous version tab. Version tabs are organized in sequential order starting from left to right, so the version tab on the left of the current version tab will be selected.

Next Tab

Selects the next version tab. Version tabs are organized in sequential order starting from left to right, so the version tab on the right of the current version tab will be selected.

Columns...

Opens the Columns dialog where you can configure the sortable columns you would like to display in your version file lists.

Filters...

Opens the Filters Manager dialog where you can manage the global file filters you would like to use for viewing your version file lists.

Refresh

Refreshes the properties of all files in the project (refreshes the project window). You can also access this menu item using F5.


Columns

Settings

Columns:

A list of the available columns that can be shown in Visual Patch. 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 Visual Patch.


Filters Manager - Overview

Filters Manager

Overview Filters

The filters manager allows you to add/remove and manage the global file filters in Visual Patch. 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 Visual Patch version file lists. 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 patch, you can use the "Missing Files" filter to see all files that cannot be found at their defined source locations.

You can access the Filters Manager by choosing View > Filters... from the program menu.

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.

Edit

Open the Filter Properties dialog where you can edit the properties of the currently selected filter.


Tools Menu

Tools Menu Commands

Overview

Project Report...

Opens the Generate Project Report dialog where you can create a detailed report of all settings in your project.

Calculate 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 patch.

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.

Calculate MD5...

Opens the Calculate File MD5 dialog, where you can calculate the MD5 digest of any file on your system. You can calculate a file's MD5 digest at runtime using Indigo Rose's Crypto Plugin.

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.


Generate Project Report

Overview

Visual Patch'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.


Calculate File CRC

Overview

Filename:

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 one of your file lists 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 project. You can paste the value by selecting Paste from the right-click context menu, or using Ctrl+V on your keyboard.


Calculate File MD5

Overview

Tip: You can calculate a file's MD5 digest at runtime using Indigo Rose's Crypto Plugin.

Filename:

The full path to the file you want to calculate the MD5 digest of. You can click the Browse button to select a file from your system.

Tip: If a file in one of your file lists is currently highlighted, its MD5 digest will automatically be calculated for you without having to browse for it.

MD5 value:

The MD5 digest value of the specified file.

Copy

Copies the value in the MD5 value field to the Windows clipboard so you can paste it somewhere within your project. You can paste the value by selecting Paste from the right-click context menu, or using Ctrl+V on your keyboard.


Help Menu

Help Menu Commands

Overview

Visual Patch Help

Opens the online help for Visual Patch.

Visual Patch User's Guide

Opens the .PDF format user's guide for Visual Patch.

What's New?

Opens the What's New in Visual Patch topic in the online help. There you will find what new features have been added to Visual Patch.

Ordering Information

Opens the Ordering Information topic in the online help where you can find ordering information for Visual Patch.

Buy Online

Opens your web browser to a web page where you can order Visual Patch and other Indigo Rose products online.

Related Products

AutoPlay Media Studio

Opens your web browser to the AutoPlay Media Studio web site. AutoPlay Media Studio allows you to create interactive front ends for CD/DVD ROMs, presentations or small stand alone applications.

Setup Factory

Opens your web browser to the Setup Factory web site. Setup Factory allows you to build professional install routines in minutes.

TrueUpdate

Opens your web browser to the TrueUpdate web site. TrueUpdate allows you to put automatic live update capabilities directly into your products.

Home Page

Opens the your web browser to the Visual Patch web site.

Technical Support

Support Options

Opens your web browser to a web page explaining your technical support options.

Contact Support...

Opens your web browser to a web page where you can submit your technical or sales related questions to our online ticket system.

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 Visual Patch is available.

About Visual Patch...

Opens the About dialog which shows the copyright and version information for Visual Patch. Use this whenever you need to find out what version and build of Visual Patch you currently have.


Miscellaneous

Contents

Please select one of the following subjects:

Error Codes

Windows Basics

ASCII Table

Authenticode Code Signing

Command Line Options

Callback Functions

Difference Files

Hidden Functions

INI Files

Input Mask

Language ID Codes

MD5 Digest

Quad-state Check Box

System Restore Monitored File Extensions

Tri-state Check Box

Virtual Key Codes

XML Actions Concepts


Error Codes - Overview

Error Codes

Overview

The following types of error codes may be generated during in Visual Patch:

  • Action Error Codes

  • Build Error Codes

  • Patch Return Codes


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

"Patch file name cannot be empty."
"Patch file name must be at least 5 characters."
"Patch 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>>."

1033

"Plugin support file: <<filename>> not found."

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>>."

2091

"File compression failed."

3010

"Failed to open config file for writing: <<config filename>>."

3012

"Failed to open patch archive for writing: <<archive filename>>."

3013

"Failed to open launcher file to archive header: <<launcher filename>>."

3014

"Could not add the data marker to the archive header."

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."

3100

"Script Error: <<location>> Line <<line number>> "Error Detail: <<error message>> in <<line in code>>."

3150

"Not enough versions in project."

3151

"No key files found in version: <<VERSION NAME>>."

3152

"No files included in version: <<VERSION NAME>>."

3200

"Error Analyzing versions."

3210

"An internal error has occurred."
"Could not create diff file: <<filename>>."
"Could not make copy of newest file: <<filename>>."

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."

7250

"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 patch manifests.

7260

"Failed to write permissions manifest to patch."

Note: See Requested User Privilege Level for more information on patch manifests.

7270

"Code sign tool executable does not exist."

7271

"Code signing certificate file does not exist or is not defined."

7272

"Code sign private key file does not exist or is not defined."

7273

"Code sign output file does not exist."

7274

"Execute program error executing code signing tool."

7280

"Warning: Skipped - Resource replacement not supported on build operating system."

7281

"Version resource replacement failed."

7282

"Icon resource replacement failed."


Patch Return Codes

Overview

The following process return codes may be returned by a patch generated with Visual Patch:

0

The patch completed successfully without any errors.

5

The patch was aborted by the user.

Note: This return code is set in the default project script using the numeric constant EXIT_REASON_USER_ABORTED.

10

Patch archive does not exist.

11

Invalid start mode: Missing __IRAFN command line switch.

12

Invalid module name.

13

Failed to initialize patch archive.

14

Failed to extract primer file.

15

Failed to extract patch data from archive.

16

Failed to find patch data file.

17

Failed to load patch data file.

18

Silent patch INI file not found.

19

Error extracting image file.

20

Archive integrity check failed.

50

Unable to open archive file.

51

Unable to allocate memory buffer.

52

Could not find data segment.

53

Could not find patch size.

54

Failed to read patch engine.

55

Unable to open patch file.

56

Could not determine a temp directory name. Try running patch.exe /T:<Path>

57

You must have at least 2MB of free space on your TEMP drive!

100

The patch was built with the evaluation version and has reached the end of its evaluation period.

101

A plugin used in the patch failed to be initialized.

102

One or more of the patch's screens could not be displayed.

103

Invalid pointer during patch execution.

104

Patch failed during application.

105

The file that will be patched could not be found.

106

An error occurred when trying to delete the original file.

107

An error occurred when trying to rename the original file.

108

There is not enough free disk space to patch the software.

109

The target drive does not exist.

1200

The user is not running with administrative privileges.

Note: This return code is set through script that is generated by the project wizard. The constant EXIT_REASON_USER_NOT_ADMIN is often used to reference the code.

1205

The software being patched is running and could not be shut down.

Note: This return code is set through script that is generated by the project wizard. The constant EXIT_REASON_PROGRAM_IS_OPEN is often used to reference the code.

1210

The software being patched could not be found on the user's system. That is, %AppFolder% was not successfully located or defined.

Note: This return code is set through script that is generated by the project wizard. The constant EXIT_REASON_CANNOT_LOCATE_SOFTWARE is often used to reference the code.

1240

The current version of the software was already installed on the user's system. No patch was necessary.

Note: This return code is set through script that is generated by the project wizard. The constant EXIT_REASON_SOFTWARE_IS_CURRENT is often used to reference the code.

1250

The system needs to be rebooted in order to complete the patch.

Note: This return code is set through script and found in the function g_HandleSystemReboot and is called on the On Shutdown event.

2000

Remove legacy file failed.

2001

Failed to backup a file.


Windows Basics

Overview

In order to use Visual Patch 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 Visual Patch 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 Visual Patch (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 Visual Patch (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 Visual Patch 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 Visual Patch 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 Visual Patch: 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 Visual Patch 3.0 is installed by default is:
    C:\Program Files\Visual Patch 3.0

  • 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 Visual Patch 3.0 application from the Program Files folder would be:
    Visual Patch 3.0\Visual Patch.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 Visual Patch 3.0 folder on a C: drive which is shared as "D2" on a computer named "R2" would be:
    \\R2\D2\Program Files\Visual Patch 3.0

  • 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 Visual Patch, 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 NT, 2000 and XP, 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. Visual Patch 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


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 |


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 patches. Due to the changes made to Internet Explorer in Windows XP SP2, Windows Vista and 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 patching 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 Patches

Once the Authenticode file signing tool is installed on your system, you are ready to start signing your patch.

  1. Before publishing your final patch, select Publish > Settings from the menu and click on the Code Signing tab.

  2. Check the "CodeSign patches" checkbox and fill in the available fields including selecting the desired tool's location on your system.

  3. Publish your final patch by selecting Publish > Build.

Tip: See the Code Signing Preferences page for configuring defaults to use for code signing your patches 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 patch executable.

Alternatively, you could simply upload the patch to a web site and then download and run it from a computer using Windows XP SP2, 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

Visual Patch'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 patching process.

Tip: The global variable _CommandLineArgs can be used to determine what arguments were passed to the patch executable.

The available command line options are grouped into the following two categories:

  • Patch Command Line Options

  • Unattended Build Options

Patch Command Line Options

The following command line options are supported by patches created with Visual Patch:

/NOINIT

This command line option hides the "initializing..." dialog that appears when extracting primer files at the beginning of the patch.

/S:<<optional ini file>>

Allow a patch 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 _SilentPatch to true if the enable silent mode 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\patch.exe" "/S:C:\patchvars.ini"

This will cause the session variables in the INI file to be used for the patch. The INI file should be in the format:

[Variables]
%AppFolder%=C:\Program Files\Your Product 2
%UserName%=Joe Blow
%Whatever%=Who knows

/T:<<file path>>

Every patch executable requires some temporary space on the user's hard drive during the patching process. By default, Visual Patch uses the user's TEMP directory for extracting temporary files and other miscellaneous operations. You can force the patch 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 patch 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\patch.exe" "/T:C:\My Temp Dir"

(forces the patch to use "C:\My Temp Dir" for temporary files)

/NOTB

Turns off the taskbar icon when executing the patch. This is the same as selecting the Hide taskbar icon option on the Advanced tab of Project Settings. This command line option is useful when running the patch in silent mode when you want it completely silent.

For example:

"C:\output\patch.exe" /S /NOTB

Unattended Build Options

The following command line options are supported by Visual Patch'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 Visual Patch build process.

/BUILD

Tells Visual Patch to build the project file passed in on the cmd line or from a batch file. For example:
"C:\Program Files\Visual Patch 3.0\Visual Patch.exe" /BUILD "C:\TestProj.vp2"

/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\Visual Patch 3.0\Visual Patch.exe" /BUILD "C:\TestProj.vp2" "/CONFIG:DebugConfig"

/LOG:<<log file path>>

Specifies the location of a log file to output the build status to. If the file exists, it will be overwritten. If the file does not exist, it will be created. For example:

"C:\Program Files\Visual Patch 3.0\Visual Patch.exe" /BUILD "C:\TestProj.vp2" "/LOG:C:\output\Log.txt"

If no log file path is specified, it will be created by default in the output directory.

/STDOUT

Makes the build status go to the standard output device (console). For example:

"C:\Program Files\Visual Patch 3.0\Visual Patch.exe" /BUILD "C:\TestProj.vp2" "/STDOUT"

/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 2002\Release
#PATCHNAME#=foobar2002patch.exe
#BUILD#=release

When you use the /CONST option along with /BUILD, the specified project file is loaded into Visual Patch, the constants described in the specified unattended-build INI file are set, and the patch executable is generated-all without any interaction.

For example:
"C:\Program Files\Visual Patch 3.0\Visual Patch.exe" /BUILD "C:\TestProj.vp2" "/CONST:C:\MyProj\Config.ini"


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 Visual Patch 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


Difference Files

Contents Overview

Creating a binary patch involves performing a byte-by-byte comparison between the original file and the new file, and then encoding the differences into a difference file. Each difference file contains the actual bytes that are different in the new file, along with a number of instructions that describe which bytes need to change, and which bytes are the same. This information is said to be encoded into the difference file.

Tip: The term “difference file” is often shortened to "diff file" or just "diff."

When the patch is applied, the difference file is decoded, and the instructions are used to build the new file by copying the "unchanged" data out of the old file, along with the "changed" data that was encoded into the difference file.

For example, given an old file "A" and a new file "B," a binary patching engine would compare A to B and then produce a difference file; let's call it "AB.diff." Once the difference file is created, you can use it to create the B file from any file that matches the A file. In fact, the binary patching engine could recreate B using A and AB.diff.

Because binary patching only stores the parts that have changed, the difference files can be very small—often less than one percent of the new file's size. The size of the difference file depends entirely on how much data has changed between the two versions.

Each difference file can update a single, specific version of a file to another single, specific version of that file. The encoded instructions in the difference file are only valid for a file that is a perfect match of the original source file. Note that binary patching cannot be used to update a file if it has been modified in any way.

For patches that need to update multiple files, the patch executable will need to contain a separate difference file for each file that needs to be updated. So, for example, to update a single file from version 1.0 or 1.1 to version 1.2, using a single patch executable, it would need to contain one difference file to go from 1.0 to 1.2, and another to go from 1.1 to 1.2.

In most cases, the difference files are so small that you can fit a lot of versions into a single patch executable and still use less space than you would by just including the whole file, as in whole-file patching.

Note: Visual Patch will automatically switch from binary to whole-file patching on a file-by-file basis whenever the total size of all the difference files surpasses the size of the whole file.

In some cases, encoding the differences between the two files results in a binary patch that is larger than just compressing the new file, for example into a .zip archive. This generally means that there are very little similarities between the two files; in other words, the two files are so different that it is difficult to reuse any of the data in the old file. This can sometimes be the case for files that are already highly compressed, or files that are encrypted. Visual Patch is able to detect these cases and will choose whichever patching method provides the best results.


Hidden Functions

Miscellaneous

Contents Hidden Functions

The following "hidden functions" are available in Visual Patch:

g_OnFileProcessed

g_OnFileProcessed (

number ResultCode,

string Filename,

string BackupFilename )

Description

This hidden function is automatically called by the patch at run time if while patching the files, a file is either patched, installed, removed, or skipped.

Some examples of where this advanced function may be useful are:

- The file needs to be added to an existing setup's uninstall so it can be removed if the user uninstalls your software.
- The file needs to be registered for the first time.
- A usage count needs to be incremented if it was installed for the first time.
- Alternate action needs to be taken if a file was skipped.

Note: If you want to use this function, you must define it somewhere in your patch before the patching stage. A good place to add this function to your project is in Global Functions. You can find this dialog by choosing Project > Resources... from the program menu and selecting the Global Functions tab.

Parameters

ResultCode

(number) The result code for the file that was processed. One of the following will be returned:

VALUE | DESCRIPTION
1 | Existing file patched.
2 | New file installed (a file was "patched" that did not previously exist).
3 | Legacy file removed.
4 | The file was skipped because a matching target file could not be found on the system.
5 | The file was skipped because of an OS or script condition failure.
6 | The file was skipped because it was already up to date (matches latest version MD5).
7 | The file was skipped because it is protected by Windows File Protection (WFP).

Filename

(string) The fully qualified path and filename of the file that was patched, installed, removed or skipped.

BackupFilename

(string) The fully qualified path and filename of the backup file of the file that was processed. This will be an empty string if a backup was not created.

Returns

Nothing.

Example

function g_OnFileProcessed(ResultCode, Filename, BackupFilename)

local CodeText = "Unknown";
if ResultCode == 1 then
CodeText = "Existing file patched";
elseif ResultCode == 2 then
CodeText = "New file installed";
elseif ResultCode == 3 then
CodeText = "Legacy file deleted";
elseif ResultCode == 4 then
CodeText = "File skipped. Matching target not found.";
elseif ResultCode == 5 then
CodeText = "File skipped. OS or script condition failure.";
elseif ResultCode == 6 then
CodeText = "File skipped. Already up to date.";
elseif ResultCode == 7 then
CodeText = "File skipped. Protected target file (WRP).";
end

local StatusMessage = "Operation: "..CodeText.."\r\n";
StatusMessage = StatusMessage.."Filename: "..Filename.."\r\n";
StatusMessage = StatusMessage.."Backup filename: "..BackupFilename;
Dialog.Message("File Processed",StatusMessage);

end

The above script illustrates the framework for the g_OnFileProcessed function that you can add to your project, such as in the Global Functions area. This example shows a dialog message displaying what was done to the current file being patched by checking the three parameters that are passed into it.


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: Visual Patch 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) | Default
 | 0x02 (2) | System Default
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
0x03 (3) |  | Catalan
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
0x06 (6) |  | Danish
0x07 (7) | 0x01 (1) | German
 | 0x02 (2) | German (Swiss)
 | 0x03 (3) | German (Austrian)
 | 0x04 (4) | German (Luxembourg)
 | 0x05 (5) | German (Liechtenstein)
0x08 (8) |  | Greek
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)
 | 0x0c (12) | English (Zimbabwe)
 | 0x0d (13) | English (Philippines)
0x0a (10) | 0x01 (1) | Spanish (Castilian)
 | 0x02 (2) | Spanish (Mexican)
 | 0x03 (3) | Spanish (Modern)
 | 0x04 (4) | Spanish (Guatemala)
 | 0x05 (5) | Spanish (Costa Rica)
 | 0x06 (6) | Spanish (Panama)
 | 0x07 (7) | Spanish (Dominican Republic)
 | 0x08 (8) | Spanish (Venezuela)
 | 0x09 (9) | Spanish (Colombia)
 | 0x0a (10) | Spanish (Peru)
 | 0x0b (11) | Spanish (Argentina)
 | 0x0c (12) | Spanish (Ecuador)
 | 0x0d (13) | Spanish (Chile)
 | 0x0e (14) | Spanish (Uruguay)
 | 0x0f (15) | Spanish (Paraguay)
 | 0x10 (16) | Spanish (Bolivia)
 | 0x11 (17) | Spanish (El Salvador)
 | 0x12 (18) | Spanish (Honduras)
 | 0x13 (19) | Spanish (Nicaragua)
 | 0x14 (20) | Spanish (Puerto Rico)
0x0b (11) |  | Finnish
0x0c (12) | 0x01 (1) | French
 | 0x02 (2) | French (Belgian)
 | 0x03 (3) | French (Canadian)
 | 0x04 (4) | French (Swiss)
 | 0x05 (5) | French (Luxembourg)
 | 0x06 (6) | French (Monaco)
0x0d (13) |  | Hebrew
0x0e (14) |  | Hungarian
0x0f (15) |  | Icelandic
0x10 (16) | 0x01 (1) | Italian
 | 0x02 (2) | Italian (Swiss)
0x11 (17) |  | Japanese
0x12 (18) | 0x01 (1) | Korean
0x13 (19) | 0x01 (1) | Dutch
 | 0x02 (2) | Dutch (Belgian)
0x14 (20) | 0x01 (1) | Norwegian (Bokmal)
 | 0x02 (2) | Norwegian (Nynorsk)
0x15 (21) |  | Polish
0x16 (22) | 0x01 (1) | Portuguese (Brazilian)
 | 0x02 (2) | Portuguese (Portugal)
0x18 (24) |  | Romanian
0x19 (25) |  | Russian
0x1a (26) |  | Croatian
0x1a (26) | 0x02 (2) | Serbian (Latin)
 | 0x03 (3) | Serbian (Cyrillic)
0x1b (27) |  | Slovak
0x1c (28) |  | Albanian
0x1d (29) | 0x01 (1) | Swedish
 | 0x02 (2) | Swedish (Finland)
0x1e (30) |  | Thai
0x1f (31) |  | Turkish
0x20 (32) | 0x01 (1) | Urdu (Pakistan)
 | 0x02 (2) | Urdu (India)
0x21 (33) |  | Indonesian
0x22 (34) |  | Ukrainian
0x23 (35) |  | Belarusian
0x24 (36) |  | Slovenian
0x25 (37) |  | Estonian
0x26 (38) |  | Latvian
0x27 (39) | 0x01 (1) | Lithuanian
0x29 (41) |  | Farsi
0x2a (42) |  | Vietnamese
0x2b (43) |  | Armenian
0x2c (44) | 0x01 (1) | Azeri (Latin)
 | 0x02 (2) | Azeri (Cyrillic)
0x2d (45) |  | Basque
0x2f (47) |  | FYRO Macedonian
0x36 (54) |  | Afrikaans
0x37 (55) |  | Georgian
0x38 (56) |  | Faeroese
0x39 (57) |  | Hindi
0x3e (62) | 0x01 (1) | Malay (Malaysia)
 | 0x02 (2) | Malay (Brunei Darassalam)
0x3f (63) |  | Kazak
0x40 (64) |  | Kyrgyz
0x41 (65) |  | Swahili
0x43 (67) | 0x01 (1) | Uzbek (Latin)
 | 0x02 (2) | Uzbek (Cyrillic)
0x44 (68) |  | Tatar
0x45 (69) |  | Bengali
0x46 (70) |  | Punjabi
0x47 (71) |  | Gujarati
0x48 (72) |  | Oriya
0x49 (73) |  | Tamil
0x4a (74) |  | Telugu
0x4b (75) |  | Kannada
0x4c (76) |  | Malayalam
0x4d (77) |  | Assamese
0x4e (78) |  | Marathi
0x4f (79) |  | Sanskrit
0x50 (80) |  | Mongolian
0x56 (86) |  | Galician
0x57 (87) |  | Konkani
0x58 (88) |  | Manipuri
0x59 (89) |  | Sindhi
0x5a (90) |  | Syriac
0x60 (96) |  | Kashmiri
0x61 (97) |  | Nepali
0x65 (101) |  | Divehi


MD5 Digest

Miscellaneous

Contents MD5 Digest

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 or contents of a file is guaranteed to produce a unique message digest. More importantly, it is virtually impossible to determine the original string or file from the digest. In other words, the MD5 calculation only works in one direction. This makes it extremely useful for storing passwords or validating the integrity of files.

Since there is no way to get from the digest back to the original text or file, 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.


Quad-State Check Box

Overview

Quad-state check boxes are used in Visual Patch 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 Visual Patch 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


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 Visual Patch Registry actions. Only the sub keys will be recreated, not their values.

Values only

Recreate the values of the selected Registry key using Visual Patch Registry actions.

Sub keys and values

Recreate both the values and sub keys of the selected Registry key using Visual Patch 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 patch so that the proper session variables are used when referencing it. The file being referenced can be part of the current version, 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.

Current Version

A list of the files currently added to the current version of your patch. You can select a file and click OK to insert the file's path reference.

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 (current version 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 patch.

Example 2

Application.Exit(4);

Immediately exits the patch 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 patch
if nChoice == 6 then
Application.Exit();
end

Confirm with the user that they wish to exit. If the choice is confirmed, exit the patch, 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.GetLanguage Examples

Application.GetLanguage

table Application.GetLanguage (

)

Example 1

tPatchLanguage = Application.GetLanguage();

Retrieves the primary and secondary patch language, and stores this information in a table called "tPatchLanguage". This information can be accessed by referencing tPatchLanguage.Primary and tPatchLanguage.Secondary.

Example 2

-- Retrieve the Patch Language
tPatchLanguage = Application.GetLanguage();

-- Check if the patch language is English (English = 9)
if tPatchLanguage.Primary == 9 then
-- Patch language is English
Dialog.Message("Patch Language", "Your patch language is English!");
else
-- Patch language is not English
Dialog.Message("Patch Language", "Your patch language is not English!");
end

Retrieves the patch 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 application 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 patch window and stores it in the variable "handle."

Example 2

-- Get the patch's window handle.
handle = Application.GetWndHandle();

-- Hide the patch's window.
Window.Hide(handle);

-- Sleep for 3 seconds.
Application.Sleep(3000);

-- Show the patch's window.
Window.Show(handle);

Gets the numeric window handle for the patch's window and stores it in the variable "handle." The window handle is then used to hide the window for 3 seconds.


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 patch.

Example 2

Application.LoadActionPlugin(Plugin_To_Load);

Loads the action plugin referenced in the variable "Plugin_To_Load" into the current patch.


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 patch 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 patch's window to the task bar.


Application.Restore Examples

Application.Restore

Application.Restore (

)

Example 1

Application.Restore();

Restores the patch'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 patch 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.SetLanguage Examples

Application.SetLanguage

Application.SetLanguage (

number Primary,

number Secondary )

Example 1

Application.SetLanguage(0,2);

Sets the patch 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 patch sleep for 1 second.

Example 2

Application.Sleep(5200);

Makes the patch 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, "Ready to Patch > 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.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 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 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 patch 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 patch's window handle.
handle = Application.GetWndHandle();

-- Hide the patch 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 patch window.
Window.Show(handle);

Hides the patch window while displaying a timed dialog message. Once the timed dialog has elapsed, the patch window is shown again.


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 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 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 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 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 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 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.


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 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 patch 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 patch 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 patch 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 patch 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 patch 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 patch 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 patch, 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 patch 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 patch 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 patch 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 patch 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 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 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 patch 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 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 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.."\\Visual Patch 3.0\\Visual Patch.exe");

Stores all of the attributes of the file named "Visual Patch.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 .vp2.
viewer_path = File.GetDefaultViewer(".vp2");

-- If there is no program association for .vp2, 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 .vp2 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 .vp2 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\\Visual Patch 3.0\\Visual Patch.exe");

Gets the "8.3" version of the file path "C:\Program Files\Visual Patch 3.0\Visual Patch.exe" and stores it in the variable "short_version." The result will look similar to "C:\PROGRA~1\VISUAL~1.0\VISUAL~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 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 its 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("joe@exampledomain.com?subject=I need help", SW_MAXIMIZE);

Opens the user's default email client, with "joe@exampledomain.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("joe@exampledomain.com?subject=Thanks%21");

Sends an email to joe@exampledomain.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 patch executable should be launched.
result = Dialog.Message("Confirm", "Are you sure you would like to patch now?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- If the user clicked the Yes button.
if (result == IDYES) then

-- Run the patch 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 patch file. If they click the Yes button, the patch 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 patch'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.


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.."\\Visual Patch 3.0");

Checks to see if the folder "Visual Patch 3.0" 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 "\Visual Patch 3.0."

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 patch 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 patch 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 patch'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", _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 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
VisualPatch.WriteToLogFile("HTTP Download Error Info: " .. http_error.Number .. " - " .. http_error.Message, true);
VisualPatch.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 Visual Patch 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="VisualPatch"}, SUBMITWEB_GET, 20, 80, nil, nil);

This example submits the query "VisualPatch" 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="VisualPatch"}, SUBMITWEB_GET, 20, 443, nil, nil);

This example submits the query "VisualPatch" 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 executable 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 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_input = seed_time..System.GetDate(DATE_FMT_JULIAN);
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_input = seed_time..System.GetDate(DATE_FMT_JULIAN);
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 a number composed of the current seconds, minutes, hours and date (in Julian format). 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 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 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 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 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 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 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 setup.msi using the MSI.RunMsiexec action.


MSI.SetInternalUI Examples

MSI.SetInternalUI

table MSI.SetInternalUI (

number UILevel,

number WindowHandle = nil )

Example 1

-- Get the extract path using a previously defined function.
strInstallerPathExtracted = g_GetExtractPath(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\\0s=YYN\\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 patch.


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 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");

Jumps to the screen named "Welcome."

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 patch.


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 patching!");

Sets the string with id "My_String" to "Hello, thank-you for patching!" 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

-- Decide which "Before Patching" screen to show.
if g_InstalledVersion then
if g_InstalledVersion == VisualPatch.GetTargetVersion() then
-- The target version was found
Screen.SetStartScreen("Software is Current");
else
-- An out-of-date version was found
Screen.SetStartScreen("Ready to Patch");
end
else
-- No version was found
Screen.SetStartScreen("Cannot Locate Software");
end

Determines if the user already has the current version of the software on their system or whether it needs to be patched. This information is gathered in order to show the appropriate first screen to the user.


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 patch 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 patch 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

sPatchMessage = SessionVar.Expand("%ProductName% v%ProductVer% Patch");

Stores a custom patch message in a string "sPatchMessage" 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("%UserName%");

Undefines the session variable %UserName%.

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.


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 = "" )

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 Visual Patch 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 Visual Patch action or any other element of your project. An example of the dialog can be seen below:

There are several actions in Visual Patch 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 Visual Patch. 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 = "4.10.2222A";

-- 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 98 Second Edition or newer 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 98 Second Edition or newer (version 4.10.2222A 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 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 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.

Note: This example works in Windows 98 First Edition, Windows 98 Second Edition, Windows 2000, and Windows XP. Windows 95 and Windows NT do not fit this model. To detect a LAN connection in all operating systems, first detect the user's OS, and the launch an appropriate detection script.


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 = "4.10.2222A";

-- 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 98 Second Edition or newer 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 98 Second Edition or newer (version 4.10.2222A 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.."\\PatchData\\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.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 patch should continue. If the system supports system restore, or the user chooses to continue, a restore point is set and the patch 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 patch should continue. If the system supports system restore, or the user chooses to continue, a restore point is set and the patch 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 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 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 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 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 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 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.


VisualPatch.CheckFolderVersion Examples

VisualPatch.CheckFolderVersion

string VisualPatch.CheckFolderVersion (

string SessionVariable,

string Folder )

Example 1

-- Define a global variable that will indicate the name
-- of the installed version on the user's system. A nil value
-- indicates that an installed version has not been found.
g_InstalledVersion = nil;

-- Location method: Current folder
-- Check whether the software is installed in the folder
-- that the patch was run from.
if not g_InstalledVersion then
g_InstalledVersion = VisualPatch.CheckFolderVersion("%AppFolder%", _SourceFolder);
if g_InstalledVersion then
SessionVar.Set("%AppFolder%", _SourceFolder);
end
end

Checks to see if the folder where the patch is running from (denoted by the global variable _SourceFolder) is found to be the application folder being searched for.

Example 2

-- Location method: Registry key
-- Read a folder path from the Registry.

if not g_InstalledVersion then
local MainKey = HKEY_CURRENT_USER;
local SubKey = SessionVar.Expand("Software\\Your Company\\Your Product");
local ValueName = "InstallFolder";
local FolderPath = Registry.GetValue(MainKey, SubKey, ValueName);
g_InstalledVersion = VisualPatch.CheckFolderVersion("%AppFolder%", FolderPath);
if g_InstalledVersion then
SessionVar.Set("%AppFolder%", FolderPath);
end
end

Checks to see if the folder path read from a Registry key is found to be the application folder being searched for.


VisualPatch.GetLocalizedString Examples

VisualPatch.GetLocalizedString

string VisualPatch.GetLocalizedString (

string StringID )

Example 1

sLocalSuccess = VisualPatch.GetLocalizedString("MSG_SUCCESS");

Gets the localized "success" string and stores it in string sLocalSuccess.


VisualPatch.GetTargetVersion Examples

VisualPatch.GetTargetVersion

string VisualPatch.GetTargetVersion (

)

Example 1

-- Define a global variable that will indicate the name
-- of the installed version on the user's system. A nil value
-- indicates that an installed version has not been found.
g_InstalledVersion = nil;

-- Location method: Current folder
-- Check whether the software is installed in the folder
-- that the patch was run from.
if not g_InstalledVersion then
g_InstalledVersion = VisualPatch.CheckFolderVersion("%AppFolder%", _SourceFolder);
if g_InstalledVersion then
SessionVar.Set("%AppFolder%", _SourceFolder);
end
end

-- Set session variables that will be used in the log file
-- and in the user interface.
if g_InstalledVersion then
SessionVar.Set("%InstalledVersion%", g_InstalledVersion);
SessionVar.Set("%TargetVersion%", VisualPatch.GetTargetVersion());
end

Determines if the folder where the patch is running from contains a valid version of the application. If it does, session variables are created to hold the installed version and current version (or target version) strings.

Example 2

-- Decide which "Before Patching" screen to show.
if g_InstalledVersion then
if g_InstalledVersion == VisualPatch.GetTargetVersion() then
-- The target version was found
Screen.SetStartScreen("Software is Current");
else
-- An out-of-date version was found
Screen.SetStartScreen("Ready to Patch");
end
else
-- No version was found
Screen.SetStartScreen("Cannot Locate Software");
end

Determines if the user already has the current version of the software on their system or whether it needs to be patched. This information is gathered in order to show the appropriate first screen to the user.


VisualPatch.SetLocalizedString Examples

VisualPatch.SetLocalizedString

VisualPatch.SetLocalizedString (

string StringID,

string Text )

Example 1

VisualPatch.SetLocalizedString("MSG_SUCCESS", "Whatever just happened worked!");

Sets the "Success" string of the current language to "Whatever just happened worked!".


VisuaPatch.WriteToLogFile Examples

VisualPatch.WriteToLogFile

VisualPatch.WriteToLogFile (

string Text,

boolean AddTimestamp = true )

Example 1

VisualPatch.WriteToLogFile("ERROR: " .. Application.GetLastError(), true);

Outputs the current application error to the patch log file.

Example 2

err = Application.GetLastError();

if err ~= 0 then
sMessage = "####################\r\n" .. "ERROR " .. err .. ": " .. _tblErrorMessages[err] .. "\r\n####################\r\n";
VisualPatch.WriteToLogFile(sMessage, false);
end

If an error occurs, outputs a nicely formatted string into the patch log file.


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 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 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 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 patch 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 patch'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 patch's window handle.
handle = Application.GetWndHandle();

-- Hide the patch window.
Window.Hide(handle);

-- Sleep for 3 seconds.
Application.Sleep(3000);

-- Show the patch window.
Window.Show(handle);

Gets the numeric window handle for the patch 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 patch's window handle.
handle = Application.GetWndHandle();

-- Hide the patch's window.
Window.Hide(handle);

-- Sleep for 3 seconds.
Application.Sleep(3000);

-- Show the patch'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 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 Visual Patch 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 lists 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 Visual Patch version file lists.

Example 2:

To filter your file lists 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 Visual Patch file lists.

Example 3:

To filter your file lists 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 Visual Patch file lists.

Example 4:

To filter your file lists 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 Visual Patch file lists.

Example 5:

To filter your file lists so it only displays files whose dates are later than January 31st 2005, the filter properties would look like the following:

Property: Date
Rule: Greater Than
Criteria: 2005-01-31

When this filter is applied, only files whose dates are later than January 31st 2005 will be shown in the Visual Patch file lists.

Note: File dates must be in the format YYYY-MM-DD.


Add New Language

Overview

Adding a new language to your project means that you want the patch to detect that language and use its corresponding language message file and translated screens.

Available languages:

A list of the languages you can detect in your patch. You can select the language you wish to support in your patch 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 Visual Patch's web site, www.visualpatch.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.


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 patch 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 Visual Patch:

*.apm; *.bmp; *.emf; *.gif; *.jpg; *.pcd; *.pcx; *.png; *.psd; *.tga; *.tif; *.wmf

Note: For optimal performance, 24 bit images should be used. 32 bit images are not supported.

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. 32 bit images are not supported.

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. 32 bit images are not supported.

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.

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.


Version Properties

Overview

Version number:

The number you want to give the version. Generally this value is something like 2.1 or 2.0.0.1.

Source folder:

The folder where Visual Patch can find all files that are part of this version. You can click the Browse button to select a folder from your system.

Recursive

Whether or not to recurse subdirectories when adding the version's files. If this option is checked, Visual Patch will add all files within any subfolders of the Source folder. If this option is not checked, only files in the root of the Source folder will be added.

Key file:

The file you want to designate as a key file for the version. Key files are files unique to each version that are used to identify what version of the application is on the user's system. For example, this file may be the application's executable that usually changes between versions.


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 Visual Patch. All available script files can be found in the Scripts folder, normally located in C:\Program Files\Visual Patch 3.0\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.


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 patch exits:

Delete this primer file from the user's system if the patch exits in any way.

Build configurations:

The build configurations that will include the current primer file. You can check or uncheck the boxes in the build configurations tree.


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 project.

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 project.

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 project.

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 project.

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 project, 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 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 project.

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


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 patch.

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 patch.

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 patch.

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 patch.

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 patch.

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 patch.

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 Visual Patch 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 patch.

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 patch.

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 patch.

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 patch.

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 patch.

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 project, 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 project.

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 project.

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\Visual Patch\3.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

Before Patching

Show the added screen in the Before Patching list of available screens.

While Patching

Show the added screen in the While Patching list of available screens.

After Patching

Show the added screen in the After Patching list of available screens.


Screen Gallery

Overview

Screens:

A list of all of the available screens that can be added at this stage of the patch. 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.


While Patching

Progress Screens Properties

While Patching

The While Patching tab is used to configure the type of progress screen you want to show while your application's files are being patched.

Progress Screen

Type:

The type of progress screen currently configured to display during the patching 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.

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 progress screen as it will appear during the patch.

Note: Since this screen displays dynamic content during the patch, some content will not appear during a preview of the screen.


Tools - Overview

Tools

Overview

The following tools are available in Visual Patch:

  • Generate Project Report

  • Calculate File CRC

  • Calculate File MD5