Introduction

Contents

Welcome to TrueUpdate!

Please select one of the following subjects:

What is TrueUpdate?

Key Features of TrueUpdate

What's New in TrueUpdate?

Frequently Asked Questions

Importing TrueUpdate 1.0 Projects

The TrueUpdate Interface

Updates 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

Program Reference

Windows Basics

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 TrueUpdate?

Introduction

TrueUpdate is the finest toolkit available for adding a sophisticated software updating and patch management solution to both software products and network infrastructure. Whether you're a software developer needing to add a "Check for Update" feature to your program, or you're a network administrator wanting to automate the detection and application of system patches to hundreds or thousands of computer systems in your organization, TrueUpdate is an excellent solution.

In either case, the benefits include lower technical support costs, faster time-to-market, more frequent bug fixes, hassle-free security updates and quicker feature additions. Additionally, TrueUpdate was designed from the ground up to be flexible, easy to use, and easy to integrate. It's a solution that can be implemented with a minimum of effort so you can realize positive returns as quickly as possible.

In TrueUpdate, 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 introduced a customizable screen manager, support for secure data transfer, project themes (skins) and many other powerful and time-saving features.

What is TrueUpdate?

TrueUpdate is a comprehensive solution for software developers, network administrators and IT departments wanting to integrate automated update capabilities into their software and business processes. TrueUpdate provides a sophisticated client/server framework for determining required updates and then retrieving and applying the necessary patch or installation files using Internet or LAN protocols.

TrueUpdate was designed to meet the demand for a complete, web-enabled software updating solution that can be integrated quickly and easily into new and existing software products and networks, regardless of the installation and deployment methods used. TrueUpdate makes adding software update and patch management capability to a company's development infrastructure as simple and cost effective as possible.

TrueUpdate can be used to securely update any electronic content, from software applications and operating system patches to time sensitive data such as product catalogs, spreadsheets, financial information, sales figures and budgets. Additionally, TrueUpdate is extremely easy to integrate into your applications and offers nearly unlimited flexibility and customization options to ensure that your particular update requirements and goals are met.

The TrueUpdate brand is a recognizable mark of quality that you can proudly display to assure your clients and customers that your software updates are in the hands of the experts.


Key Features of TrueUpdate

Introduction

Contents Key Features of TrueUpdate

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/Window 8 Compatible

TrueUpdate's design workspace and generated updates are compatible with Windows Vista, Windows 7 and Windows 8 including a configurable "requested execution level" setting for the update's manifest.

Custom Resource Stamping

TrueUpdate allows you to use your own product icon and provides control of the resource information that you want written into the update's resources.

Integrated Code Signing

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

MSI Actions

Over 35 MSI actions that leverage the Windows Installer service technology on the user's system. These are perfect for adding Windows Installer functionality to your update.

Dynamic Control of Client Systems

Once the TrueUpdate Client application is installed on a computer system, you have everything you need to ensure that the system is always up-to-date with the latest software and patches. Operating in conjunction with a TrueUpdate Server connection, the client software can be continually modified and reconfigured to carry out whatever system modification you require. This completely dynamic system puts you in full control and affords you flexibility that other products simply cannot match.

You Control the Server

With TrueUpdate, there is no need to relinquish control over the reliability of your update process. Other services lock you into using their servers; with TrueUpdate, you decide where your update files are hosted. You decide on the level of redundancy. You are in control of your update files, patches and servers. There is no need to rely on the uncertain future of an "update service", pay exorbitant annual fees or wait helplessly during downtimes you are powerless to resolve.

Industry Standard Protocols and Servers

TrueUpdate uses readily available client/server technologies rather than the proprietary servers required by competitive products. By making use of affordable and trusted protocols such as HTTP, HTTPS and FTP, organizations of any size can deploy TrueUpdate enabled software without the need for specialized and costly hardware and software platforms. TrueUpdate is built on the trusted, dependable standards you already rely on.

Easy to Integrate

TrueUpdate was designed to minimize the time it takes to add automated update capabilities to software applications. As a compact and standalone executable, the TrueUpdate Client application is extremely easy to integrate into your software. A typical software developer can have it done in only a few hours, and it doesn't matter what language you are working in – TrueUpdate is compatible with everything from Visual Basic to Delphi, C++, COBOL or whatever you are working with. In fact, it was designed from the ground up to be flexible, easy to use, and easy to integrate.

Runs Stand-alone or Embedded

The TrueUpdate Client application can be invoked in a variety of ways, depending on your particular needs. Software developers can easily embed the client software directly into their application, making use of the extensive "theme" support to match their own unique look and feel. Network administrators, meanwhile, can simply install the client application on each system and configure an appropriate execution schedule using standard system tools.

Automates Complex Tasks

TrueUpdate is built on a powerful scripting engine that is capable of quickly processing any of the more than 250 included high-level actions. Featuring 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 updating requirements. No other tool gives you the same level of ready-to-use commands. TrueUpdate helps you to get your job done both faster and better!

Scalable and Fault-Tolerant

From the ground up, TrueUpdate was created to be fully scalable and fault-tolerant. It's easy to configure the client application to access redundant servers. If a server is unavailable for any reason, the client will move on to the next one until it can establish a connection. Additionally, since you control the underlying server technology such as HTTP, HTTPS, FTP or LAN, you have ultimate control over load-balancing and distributed processing of client/server requests.

Reduces Costs

Automating the update process saves considerable time and expense. For software vendors, it reduces support costs by making it easier for your users to keep their software up to date—giving your tech support department fewer legacy support issues to deal with. And for network administrators who maintain hundreds or thousands of systems, the benefits of TrueUpdate far outweigh the initial investment.

Lightweight and Stand-alone

Written completely in optimized C and C++ code, the TrueUpdate client is small, weighing in around 500K in size. It's also completely self-contained—the TrueUpdate client has no external dependencies, so you don't have to distribute any extras to make it work. Unlike competitive products, it doesn't require the Java runtime, Visual Basic runtime, .NET framework or any other multi-megabyte runtime engine.

Works with Any Patch/Install Builder

TrueUpdate works with your choice of installation and patching tools. For a complete and fully integrated end-to-end solution, we'd recommend choosing Indigo Rose's Setup Factory and Visual Patch; however you're certainly not locked into doing so. If your company has standardized on other install/patch builders, such as those offered by Installshield, Wise or ZeroG, TrueUpdate can accommodate them. In fact, TrueUpdate is even able to work with zip archives and individual data files, should you desire.

Trusted by Professionals

Thousands of software developers trust Indigo Rose software tools. In fact, our products such as TrueUpdate, Setup Factory and Visual Patch are used to distribute and manage software on millions of customer and client systems around the world. While others have tried to imitate it, only TrueUpdate offers such a perfect combination of flexibility, customizability, ease of use and value.


What's New in TrueUpdate?

Introduction

Contents What's New in TrueUpdate?

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 Compatible

TrueUpdate's design workspace and generated updates are compatible with Windows Vista, Windows 7, and Windows 8 including a configurable "requested execution level" setting for the update's manifest. Other features enhanced for Vista or later include: System.GetOSName, System.GetOSVersionInfo, System.GetUserInfo and File.Run actions.

Custom Resource Stamping

TrueUpdate allows you to use your own product icon and provides control of the resource information that you want written into the update's resources.

Integrated Code Signing

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

MSI Actions

Over 35 MSI actions that leverage the Windows Installer service technology on the user's system. These are perfect for adding Windows Installer functionality to your update.

Enhanced Design Performance

Reduced the loading time of the TrueUpdate design environment.

HTTP Action Enhancements

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

Extensive Project Wizard

Getting your project started has never been easier, thanks to the Project Wizard. You'll be walked through each step of the process, including setting up your TrueUpdate Server, choosing download methods, customizing the TrueUpdate Client and configuring your automatic upload settings. The wizard includes dozens of options and project templates to choose from.

More Server Types

TrueUpdate supports all of the most popular protocols for client/server communication. This includes HTTP, FTP and LAN (both UNC paths and mapped drives), as well as secure connections and file transfers using HTTPS. Full support for HTTP basic authentication, timeouts, ports, FTP passive mode, usernames and passwords is also built-in.

Automatic Firewall and Proxy Server Detection

TrueUpdate handles proxy servers and firewalls in an entirely seamless and industry-standard manner. All Internet communication is now done entirely through the WinINet API, making it fully compatible with any corporate network hardware and software that supports standard Windows/Internet Explorer functionality.

Supports More Patching Methods

It doesn't matter what method you plan to use to patch/update the software on the client system. TrueUpdate can work with them all. Whether you're deploying a self-contained patch executable (such as those created by Visual Patch), a single-file installer (like those created with Setup Factory), zip files, individual data files, multiple binary patch files or whatever else you require, TrueUpdate can handle it. We've even included a variety of project templates and samples to get you started.

Sophisticated Version Analysis

TrueUpdate provides many flexible methods for analyzing existing software versions on the client system. It can access the registry, read values from INI files, compare file CRC values, query file version resource information or even use time/date stamps if necessary. Once a version has been identified, TrueUpdate can use a series of actions to bring that version up to date as required.

Powerful Scripting Engine

TrueUpdate includes the same scripting engine as Setup Factory 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 updating 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 update tasks.

Extensive Action Library

TrueUpdate 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. There is also a full suite of file download actions including FTP, HTTP and secure HTTPS transfers, including new automatic support for firewalls and proxy servers.

Easy to Use Action Wizard

You don't have to be a wizard to create powerful update systems with TrueUpdate. 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. 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.

Color Syntax Highlighting Script Editor

The TrueUpdate script 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.

Improved Client Interface

TrueUpdate gives you nearly unlimited flexibility in designing the user interface. You can choose from a fully interactive wizard, a minimal dialog box style, a completely silent approach or a "silent until update available" system. Additionally, thanks to the new screen gallery and manager, you can choose from over 25 ready to use wizard-style dialogs, or customize them to fit your needs.

Screen Gallery & Manager

With a library of more than twenty-five different screen templates to choose from, TrueUpdate is miles ahead of both previous versions and the competition. There are pre-built layouts to handle just about any task you can dream up, and it's easy to adjust them to fit your needs exactly. You'll find check boxes, radio buttons and edit fields to popular screens like license agreements, folder selection and other advanced options. The Screen Manager allows you to add and remove screens at will and adjust the sequence with a simple drag-and-drop motion. Each screen features a real-time preview so you can see the result of your changes as you work.

Themes and Skins

Choose from over twenty included themes (skins) for your project 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.

Publishing Wizard

Once you've got your project ready to go, the Publishing Wizard will help you to package it up and upload it to your server. The wizard will create the client application, server configuration files and everything else you need to put your update system into operation. You'll also get a full project manifest that tells you what files have been generated and what you need to do with them.

Automatic Server Uploads with Secure FTP Support

TrueUpdate makes it easy to keep both your client and server files up-to-date. The new automatic upload feature turns the build process into a complete publishing solution. It supports file copying to UNC or mapped drives, standard FTP, or secure SFTP. Of course, should you wish to handle it all yourself, there is a manual upload option as well.

Compact Client Application

Smaller and faster means a better experience, and TrueUpdate delivers. Compare our tiny ~500 KB client application to the competition and see for yourself. And since it is written completely in optimized C++ code, there are no external dependencies or runtimes required.

Encrypted Configuration Files

Both client configuration files and server data files are automatically compressed and encrypted using your own private key. Featuring the secure Blowfish algorithm, your scripts and configuration info are safe from any casual tampering or viewing.

Runs Silent or Interactive

Your TrueUpdate projects can be configured to operate without displaying user interface dialogs, prompts, messages or errors. Silent operation lets you maintain control over hundreds or thousands of workstations while enforcing corporate standards. The client application can easily be called from programs, system schedulers or automatic processes.

Expandable with Action Plugins

TrueUpdate can be easily expanded with Action Plugins. These plug-in modules can extend the product in infinitely powerful ways, such as adding support for SQLite databases, XML, MD5 hashing, data encryption and much more. Tight integration with the design environment – including IntelliSense style code completion and syntax highlighting – makes them just as easy to use as built-in actions. Plugins are available through Indigo Rose as well as third-party developers thanks to Indigo Rose's freely available plug-in development kit.

International Language Support

TrueUpdate offers unsurpassed support for multilingual projects right out of the box. Update systems created with TrueUpdate 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, you simply provide the text and TrueUpdate 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. Basically anywhere you can type, you can perform a spell check to ensure error-free text. Dictionaries are available for over a dozen languages including English, French, German, Italian, Spanish, Dutch, Swedish, Danish, Croatian, Czech, Polish and Slovenian.

Client Log Files

The client application can easily log each action giving you an accurate record of everything that is happening behind the scenes. It's perfect for debugging or even archiving. You can control the level of detail being logged, including options for recording script actions.

Unattended Builds

TrueUpdate fits seamlessly into your daily build process. Creating your update project every time you build your source code makes it easy to test early and often. Used in conjunction with design-time constants (e.g. DEFINE's) and build response files, your TrueUpdate project can be kept up to date simply and automatically.

Works with Windows 95 and Up

Update systems created with TrueUpdate work just fine on every Windows operating system from Windows 95 to Windows 8 and beyond. 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

Who needs TrueUpdate?

Software developers, network administrators and end-users alike share in the benefits of TrueUpdate enabled software. Developers appreciate it for the control it gives them over software that has already been deployed. Network administrators benefit from improved security and better control of network nodes. End-users see TrueUpdate enabled software as an assurance of quality – a symbol that the developer is there to stand behind their product.

Any company who develops software applications or distributes data needs TrueUpdate. Any organization that needs to ensure its network is secure and updated with the latest patches needs TrueUpdate. Anyone who needs timely and secure synchronization of documents and files needs TrueUpdate.

Ensuring that everyone is using the most recent point release of a particular package makes good sense. It eliminates legacy technical support calls, and corresponding user frustration. It ensures that data is current. It also serves to maintain customer satisfaction. And that's something everyone can appreciate.

What can you do with TrueUpdate?

Software that is TrueUpdate enabled can quickly and efficiently determine if it is "out of date". TrueUpdate uses Internet enabled "client-pull" technology to retrieve and apply required patch files or modifications. By making use of industry standard protocols like HTTP, HTTPS and FTP, TrueUpdate is able to efficiently interact with either local or remote servers.

Adding TrueUpdate to your product makes it extremely easy to manage, control and update "in the field". A traditional release cycle would dictate that once your application or data files were released to customers, clients or other end-users, it was static, expensive and time-consuming to alter. However, once you add TrueUpdate to your application, you'll be able to easily update your product or data as often as you require.

What's wrong with traditional update methods?

One of the most serious problems with traditional update methods is that they require the users to do most of the work. The problem with relying on an update process that demands too much user involvement is obvious; the users might decide it isn't worth the hassle to keep their systems up to date. This results in a higher incidence of legacy support issues, more security holes and other related problems. Additionally, when users don't update, they don't benefit from bug fixes and product improvements. TrueUpdate helps solve all of these problems.

What is automated updating?

Automated updating is the ability of software to handle some or all of the update process so the user doesn't have to. The update process consists of all the steps required to determine whether a newer version exists for a given piece of software, as well as all the steps required to bring an older version up to date. Automating the update process allows software to keep itself current after it has been deployed to users.

How important is automated updating?

Today's rapid product cycles, security vulnerabilities and short turnaround times make it more important than ever to get new versions into the hands of users quickly and efficiently. The Internet has created a highly competitive market where users expect immediate results and the prize often goes to the company that reacts the most quickly to changes in user needs and perceptions. In order to streamline software deployment, it is becoming increasingly desirable for software authors to incorporate automated updating abilities into their software.

How does TrueUpdate 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. 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.

Why add TrueUpdate to your software application?

In a traditional release cycle, once your application or data files are released to customers, clients or other end-users, they are static, expensive and time-consuming to alter. However, once you add TrueUpdate to your application, you'll be able to easily update your product or data as often as you require.

From the developer's point of view, when a new software release is available – perhaps a bug has been fixed – TrueUpdate makes it trivial to publish the changes and bring all of your users up to date. The next time the user runs the application, TrueUpdate will detect that a new release is available and take steps to handle it.

How easy is it to add TrueUpdate to an application?

As a self-contained executable, the TrueUpdate client can be integrated into your application in less than a day. While the actual time required depends on the amount of integration you desire and your level of programming knowledge, most developers should be able to complete the job in just a few hours. We even include sample source code for adding a "Check for Update" menu command and tips to get you going.

Alternatively, the TrueUpdate client executable can be distributed directly, rather than being embedded within an application. This allows the TrueUpdate client to be called manually from the start menu, from a shortcut on the user's desktop or automatically with system schedulers. This method of adding TrueUpdate to your application is as easy as installing a shortcut onto the user's system.

How does TrueUpdate impact technical support?

TrueUpdate allows 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 TrueUpdate 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 updating the software as easy as possible. Making it easy for users to update your software shows that you're committed to supporting it.

How does TrueUpdate 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 TrueUpdate, the task is virtually impossible. By installing the TrueUpdate client onto your networked computers, you'll be able to quickly and effectively roll out whatever software you want throughout your organization. The client software can analyze the computer system, decide what is currently installed and then take whatever actions you determine are needed to bring that system up-to-date. It's fast, easy and automatic.

I'm not a developer...do I still need TrueUpdate?

Absolutely! You don't need to be a software developer to benefit from TrueUpdate. As a stand-alone executable, the TrueUpdate client can be used to update all kinds of files. You could use TrueUpdate to distribute product catalogs to your sales teams, or to remotely configure system files across your corporate network. Price lists, help files, quarterly reports, internal support videos—TrueUpdate can help you keep anything up to date.

Does TrueUpdate actually install files?

With a full suite of file operations, including specialized actions to download, copy, delete, rename and even zip and unzip files, TrueUpdate may be all you need to install files onto a user's system. For situations requiring a more manageable and compartmentalized solution to file installation and patching, we'd recommend using Indigo Rose's Setup Factory and Visual Patch products. Used in conjunction with TrueUpdate, these products make up a complete and robust software deployment and management solution.


Importing TrueUpdate 1.0 Projects

Overview What Is Converted What Is Not Converted

This topic serves as an introduction to the project conversion process from TrueUpdate 1.0 to TrueUpdate 3.0. It will describe what the project converter can and cannot convert. It will also explain some of the reasons behind the decisions made and what to do once your TrueUpdate 1.0 project has been converted to TrueUpdate 3.0.

Introduction

TrueUpdate was rebuilt from the ground up to be infinitely more powerful and flexible than its previous version. As such, it required an entirely new "scripting engine" to process actions and a new screen structure. The importer converts as much information from TrueUpdate 1.0 to TrueUpdate 3.0 as possible, however some conversions are impossible due to the large paradigm shift from TrueUpdate 1.0 to 3.0.

Converting Projects from v1.0 to v3.0

Given the changes to the scripting engine and overall framework in v3.0, you'll need to decide whether or not to automatically convert your v1.0 projects to v3.0 projects. The converter is not a one-to-one conversion; instead it converts your TrueUpdate 1.0 project into doing things the TrueUpdate 3.0 way. While the converter will attempt to make the best decisions possible when converting your project, it is no substitute for a seasoned developer. Whenever possible, it is recommended that you manually convert your TrueUpdate 1.0 projects over to TrueUpdate 3.0 to ensure that your design is converted properly.

For the most part everything in your TrueUpdate 1.0 project will be converted over to 3.0 properly, with a few exceptions listed in the What Is Not Converted topic. That being said, it is important to read this document to know the limitations of the conversion process and to test your converted project fully before distributing.

This guide will look at the conversion process from the TrueUpdate 1.0 standpoint. To start a conversion, simply go to File > Open, select the version 1.0 file type from the files of type dropdown, and select either a v1.0 client configuration project file (.tup) or a server file project (.uif). Once one of the two project files has been selected, a dialog will be shown allowing you to browse for the remaining project file, and configure the converted project's path and filename. The conversion tool will then take over and do its best to create a v3.0 compatible project from your v1.0 project files.

Where Do I Go Next?

You'll definitely want to read the rest of the topic, including the What Is Converted and What is Not Converted sections. That'll give you an exact rundown of what to expect from the automated conversion process. Then you'll want to become more familiar with all of the goodies you'll find in v3.0. They'll make your updates cooler and more professional!

The first section to read in the help file should be the Key Features of TrueUpdate section. This will help point out all of the exciting features available in TrueUpdate. There is also the What's New in TrueUpdate? topic that covers what new features have been added. The next section to take a look at is the topic, The TrueUpdate Interface. This will provide a brief tour of the design environment so you are familiar with the terms used throughout the rest of the documentation.

If you are still not sure how things work in TrueUpdate, 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. The User's Guide can be accessed from the Help program menu.

If you think that you have a good handle on what "the TrueUpdate 3.0" way entails, but are looking for some specific real world examples, visit www.indigorose.com for available support resources and policies. This area provides various articles answering some of the most common questions we have been asked about TrueUpdate. TrueUpdate also contains a "Samples" folder in the main TrueUpdate program directory providing sample projects that you can look at and work off of.

At this point you should know almost everything there is to know about TrueUpdate, however your actions will look different after being converted to TrueUpdate 3.0 script. For this reason, you should read over the Scripting Guide located in the Help file. This guide will provide you with tips, tricks, and professional-level techniques you should use when writing or modifying your TrueUpdate scripts.


The TrueUpdate Interface

Introduction

Contents The TrueUpdate Interface

The TrueUpdate 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 from the program menu.

Most of the program window is taken up by the Client Script and Server Script tabs. The Client Script tab contains the script that is run when your update is launched. Its main function is to get the TrueUpdate server configuration files. The Server Script tab contains the script that will be run to determine whether or not an update is required. You can switch between these scripts by clicking on their respective tabs.

The rest of the program window is made up of individual sub-windows known as panes or panels. Each panel can be docked, tabbed, pinned, resized, dragged, and even made to float on top of the design environment. There are two panels visible by default, the Screens panel and the Screen Preview panel. The Screens panel is used to add lists of screens to your update. The Screen Preview panel is used to preview how individual screens will look at runtime. Any screen that is selected in the Screens panel will display an image of that screen in the Screen Preview panel.


Updates On Windows Vista

Updates On Windows Vista or Later

Windows Vista

Overview

In general updates 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 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, 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 (TrueUpdate updates are always 32-bit).

New TrueUpdate Vista/Windows 7/Windows 8 Runtime Features

Several new features have been added to aid in the updating process on Windows Vista or later. Additional features will be added in future service releases.

  • Client update 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.

  • 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/Server 2008/Server 2008 R2/Server 2012 operating systems.

  • New return code for the File.Run action pertaining to elevation being required.

  • 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 client update executable 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 client update executable's application manifest for distribution on Windows Vista or later. When the client executable is run, the operating system reads this information to identify what privileges it requires. The default setting in TrueUpdate is "Require administrator" and should generally never be changed. You should also avoid changing the manifest setting during an update expecting it to be automatically updated. Updating an As invoker manifested client to Require administrator will fail. If for some reason you do not want to require administrator privileges to run the update 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 update 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 update as a standard user.

Important information requiring attention:

Running Programs

User Account Control (UAC) On

Problem: File.Run actions will fail for both standard users and Administrator users if Windows Vista or later identifies the target file as requiring elevation. This will happen for files containing marked application manifests requiring elevation, or detected by Windows Vista's installer detection.

Solutions: If the target file contains a proper manifest, and contains its own Administrator detection and notification, or is an install/patch/update that Vista or later will detect with its installer detection feature, use the Shell.Execute action instead. This will allow Vista or later to prompt for approval or login credentials. The second solution is to mark your update 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.

Log File

By default, the update log file is created in the Windows folder. This folder generally cannot be accessed by a user (all users initially) assigned the standard user access token. Therefore this path must be changed to a per-user writable location such as the user's Documents folder, or Application Data.

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.

Project Wizard Generated Scripts

Project wizard generated scripts generally use the File.Run action because they make use of the WaitForReturn parameter. If your project has been generated through the project wizard and you want to change the manifest to As invoker, you must change all File.Run actions to Shell.Execute actions so that Windows Vista or later can handle any elevation that may be required. Using the File.Run action to execute a file that requires elevation will fail.

Updating Client Files

TrueUpdate has the ability to update both the client executable and the client data file if newer ones are available. On the Advanced tab of Project > Settings you are able to select how you want to handle changes to these files. If you always want these files to be updated and want your update executable manifested with As invoker, you must ensure that the client files exist in a location accessible by all users such as the common application data directory (%ApplicationDataFolderCommon%). If your existing client executable is manifested with As invoker and you try to update your client executable with a Require administrator manifest using the automatic update feature, the update will fail. In this case, you must either keep your current manifest settings, or distribute a new copy of the client executable with the new manifest. Generally it is best to never change the client executable's manifest once it has been distributed the first time.

Changing to "Highest available"

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

Previously Created Updates

Updates are now properly manifested using the Requested User Privilege Level setting. Updates 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 TrueUpdate updates as an "installer type." This will automatically prompt the user for elevation or logon credentials.

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

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 update and application functionality. It is recommended that all application and update files be signed when distributed on Windows Vista or later.

TrueUpdate contains an integrated code signing procedure that allows you to code sign your client update executable with your certificate. You can find these settings on the Code Signing tab of the "Build Settings" dialog (Publish > Settings).

Note: For more information, see Authenticode Code Signing.


Introduction

TrueUpdate is the finest toolkit available for adding a sophisticated software updating and patch management solution to both software products and network infrastructure. Whether you’re a software developer needing to add a "Check for Update" feature to your program, or you’re a network administrator wanting to automate the detection and application of system patches to hundreds or thousands of computer systems in your organization, TrueUpdate is an excellent solution.

In either case, the benefits include lower technical support costs, faster time-to-market, more frequent bug fixes, hassle-free security updates and quicker feature additions. Additionally, TrueUpdate was designed from the ground up to be flexible, easy to use, and easy to integrate. It’s a solution that can be implemented with a minimum of effort so you can realize positive returns as quickly as possible.

In TrueUpdate, 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 introduced a customizable screen manager, support for secure data transfer, project themes (skins) and many other powerful and timesaving features.

What is TrueUpdate?

TrueUpdate is a comprehensive solution for software developers, network administrators and IT departments wanting to integrate automated update capabilities into their software and business processes. TrueUpdate provides a sophisticated client/server framework for determining required updates and then retrieving and applying the necessary patch or installation files using Internet or LAN protocols.

TrueUpdate was designed to meet the demand for a complete, web-enabled software updating solution that can be integrated quickly and easily into new and existing software products and networks, regardless of the installation and deployment methods used. TrueUpdate makes adding software update and patch management capability to a company's development infrastructure as simple and cost effective as possible.

TrueUpdate can be used to securely update any electronic content, from software applications and operating system patches to time sensitive data such as product catalogs, spreadsheets, financial information, sales figures and budgets. Additionally, TrueUpdate is extremely easy to integrate into your applications and offers nearly unlimited flexibility and customization options to ensure that your particular update requirements and goals are met.

The TrueUpdate brand is a recognizable mark of quality that you can proudly display to assure your clients and customers that your software updates are in the hands of the experts.

Key Features of TrueUpdate

Vista/Windows 7/Windows 8 Compatible

TrueUpdate's design workspace and generated updates are compatible with Windows Vista or later, including a configurable "requested execution level" setting for the update's manifest.

Custom Resource Stamping

TrueUpdate allows you to use your own product icon and provides control of the resource information that you want written into the update's resources.

Integrated Code Signing

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

MSI Actions

Over 35 MSI actions that leverage the Windows Installer service technology on the user's system. These are perfect for adding Windows Installer functionality to your update.

Dynamic Control of Client Systems

Once the TrueUpdate Client application is installed on a computer system, you have everything you need to ensure that the system is always up-to-date with the latest software and patches. Operating in conjunction with a TrueUpdate Server connection, the client software can be continually modified and reconfigured to carry out whatever system modification you require. This completely dynamic system puts you in full control and affords you flexibility that other products simply cannot match.

You Control the Server

With TrueUpdate, there is no need to relinquish control over the reliability of your update process. Other services lock you into using their servers; with TrueUpdate, you decide where your update files are hosted. You decide on the level of redundancy. You are in control of your update files, patches and servers. There is no need to rely on the uncertain future of an "update service", pay exorbitant annual fees or wait helplessly during downtimes you are powerless to resolve.

Industry Standard Protocols and Servers

TrueUpdate uses readily available client/server technologies rather than the proprietary servers required by competitive products. By making use of affordable and trusted protocols such as HTTP, HTTPS and FTP, organizations of any size can deploy TrueUpdate enabled software without the need for specialized and costly hardware and software platforms. TrueUpdate is built on the trusted, dependable standards you already rely on.

Easy to Integrate

TrueUpdate was designed to minimize the time it takes to add automated update capabilities to software applications. As a compact and standalone executable, the TrueUpdate Client application is extremely easy to integrate into your software. A typical software developer can have it done in only a few hours, and it doesn’t matter what language you are working in – TrueUpdate is compatible with everything from Visual Basic to Delphi, C++, COBOL or whatever you are working with. In fact, it was designed from the ground up to be flexible, easy to use, and easy to integrate.

Runs Stand-alone or Embedded

The TrueUpdate Client application can be invoked in a variety of ways, depending on your particular needs. Software developers can easily embed the client software directly into their application, making use of the extensive "theme" support to match their own unique look and feel. Network administrators, meanwhile, can simply install the client application on each system and configure an appropriate execution schedule using standard system tools.

Automates Complex Tasks

TrueUpdate is built on a powerful scripting engine that is capable of quickly processing any of the more than 250 included high-level actions. Featuring 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 updating requirements. No other tool gives you the same level of ready-to-use commands. TrueUpdate helps you to get your job done both faster and better!

Scalable and Fault-Tolerant

From the ground up, TrueUpdate was created to be fully scalable and fault-tolerant. It’s easy to configure the client application to access redundant servers. If a server is unavailable for any reason, the client will move on to the next one until it can establish a connection. Additionally, since you control the underlying server technology such as HTTP, HTTPS, FTP or LAN, you have ultimate control over load-balancing and distributed processing of client/server requests.

Reduces Costs

Automating the update process saves considerable time and expense. For software vendors, it reduces support costs by making it easier for your users to keep their software up to date--giving your tech support department fewer legacy support issues to deal with. And for network administrators who maintain hundreds or thousands of systems, the benefits of TrueUpdate far outweigh the initial investment.

Lightweight and Stand-alone

Written completely in optimized C and C++ code, the TrueUpdate client is small, weighing in around 500K in size. It's also completely self-contained--the TrueUpdate client has no external dependencies, so you don't have to distribute any extras to make it work. Unlike competitive products, it doesn't require the Java runtime, Visual Basic runtime, .NET framework or any other multi-megabyte runtime engine.

Works with Any Patch/Install Builder

TrueUpdate works with your choice of installation and patching tools. For a complete and fully integrated end-to-end solution, we’d recommend choosing Indigo Rose’s Setup Factory and Visual Patch; however you’re certainly not locked into doing so. If your company has standardized on other install/patch builders, such as those offered by Installshield, Wise or ZeroG, TrueUpdate can accommodate them. In fact, TrueUpdate is even able to work with zip archives and individual data files, should you desire.

Trusted by Professionals

Thousands of software developers trust Indigo Rose software tools. In fact, our products such as TrueUpdate, Setup Factory and Visual Patch 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 TrueUpdate?

Vista/Windows 7/Windows 8 Compatible

TrueUpdate's design workspace and generated updates are compatible with Windows Vista or later, including a configurable "requested execution level" setting for the update's manifest. Other features enhanced for Vista include: System.GetOSName, System.GetOSVersionInfo, System.GetUserInfo and File.Run actions.

Custom Resource Stamping

TrueUpdate allows you to use your own product icon and provides control of the resource information that you want written into the update's resources.

Integrated Code Signing

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

MSI Actions

Over 35 MSI actions that leverage the Windows Installer service technology on the user's system. These are perfect for adding Windows Installer functionality to your update.

Enhanced Design Performance

Reduced the loading time of the TrueUpdate design environment.

HTTP Action Enhancements

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

Extensive Project Wizard

Getting your project started has never been easier, thanks to the new Project Wizard. You’ll be walked through each step of the process, including setting up your TrueUpdate Server, choosing download methods, customizing the TrueUpdate Client and configuring your automatic upload settings. The wizard includes dozens of options and project templates to choose from.

More Server Types

TrueUpdate supports all of the most popular protocols for client/server communication. This includes HTTP, FTP and LAN (both UNC paths and mapped drives), as well as secure connections and file transfers using HTTPS. Full support for HTTP basic authentication, timeouts, ports, FTP passive mode, usernames and passwords is also built-in.

Automatic Firewall and Proxy Server Detection

TrueUpdate now handles proxy servers and firewalls in an entirely seamless and industry-standard manner. Internet communication is now done entirely through the WinINet API, making it fully compatible with any corporate network hardware and software that supports standard Windows/Internet Explorer functionality.

Supports More Patching Methods

It doesn’t matter what method you plan to use to patch/update the software on the client system; TrueUpdate can work with them all. Whether you’re deploying a self-contained patch executable (such as those created by Visual Patch), a single-file installer (like those created with Setup Factory), zip files, individual data files, multiple binary patch files or whatever else you require, TrueUpdate can handle it. We’ve even included a variety of project templates and samples to get you started.

Sophisticated Version Analysis

TrueUpdate provides many flexible methods for analyzing existing software versions on the client system. It can access the registry, read values from INI files, compare file CRC values, query file version resource information or even use time/date stamps if necessary. Once a version has been identified, TrueUpdate can use a series of actions to bring that version up to date as required.

Powerful Scripting Engine

TrueUpdate includes the same scripting engine as Setup Factory 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 updating 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 update tasks.

Extensive Action Library

TrueUpdate includes a built-in library of more than 250 powerful yet easy to use actions. Here, you’ll find 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. There is also a full suite of file download actions including FTP, HTTP and secure HTTPS transfers, including new automatic support for firewalls and proxy servers.

Easy to Use Action Wizard

You don’t have to be a wizard to create powerful update systems with TrueUpdate. 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. 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.

Color Syntax Highlighting Script Editor

The TrueUpdate script 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.

Improved Client Interface

TrueUpdate gives you nearly unlimited flexibility in designing the user interface. You can choose from a fully interactive wizard, a minimal dialog box style, a completely silent approach or a "silent until update available" system. Additionally, thanks to the new screen gallery and manager, you can choose from over 25 ready to use wizard-style dialogs, or customize them to fit your needs.

Screen Gallery & Manager

With a library of more than 25 different screen templates to choose from, TrueUpdate is miles ahead of both previous versions and the competition. There are pre-built layouts to handle just about any task you can dream up, and it’s easy to adjust them to fit your needs exactly. You’ll find check boxes, radio buttons and edit fields to popular screens like license agreements, folder selection and other advanced options. The Screen Manager allows you to add and remove screens at will and adjust the sequence with a simple drag-and-drop motion. Each screen features a real-time preview so you can see the result of your changes as you work.

Themes and Skins

Choose from over twenty included themes (skins) for your project 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.

Publishing Wizard

Once you’ve got your project ready to go, the Publishing Wizard will help you to package it up and upload it to your server. The wizard will create the client application, server configuration files and everything else you need to put your update system into operation. You’ll also get a full project manifest that tells you what files have been generated and what you need to do with them.

Automatic Server Uploads with Secure FTP Support

TrueUpdate makes it easy to keep both your client and server files up-to-date. The new automatic upload feature turns the build process into a complete publishing solution. It supports file copying to UNC or mapped drives, standard FTP, or secure SFTP. Of course, should you wish to handle it all yourself, there is a manual upload option as well.

Compact Client Application

Smaller and faster means a better experience, and TrueUpdate delivers. Compare our tiny ~500 KB client application to the competition and see for yourself. And since it is written completely in optimized C++ code, there are no external dependencies or runtimes required.

Encrypted Configuration Files

Both client configuration files and server data files are automatically compressed and encrypted using your own private key. Featuring the secure Blowfish algorithm, your scripts and configuration info are safe from any casual tampering or viewing.

Runs Silent or Interactive

Your TrueUpdate projects can be configured to operate without displaying user interface dialogs, prompts, messages or errors. Silent operation lets you maintain control over hundreds or thousands of workstations while enforcing corporate standards. The client application can easily be called from programs, system schedulers or automatic processes.

Expandable with Action Plugins

TrueUpdate can be easily expanded with Action Plugins. These plug-in modules can extend the product in infinitely powerful ways, such as adding support for SQLite databases, XML, MD5 hashing, data encryption and much more. Tight integration with the design environment – including IntelliSense style code completion and syntax highlighting – makes them just as easy to use as built-in actions. Plugins are available through Indigo Rose as well as third-party developers thanks to Indigo Rose’s freely available plug-in development kit.

International Language Support

TrueUpdate offers unsurpassed support for multilingual projects right out of the box. Update systems created with TrueUpdate 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, you simply provide the text and TrueUpdate 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. Basically anywhere you can type, you can perform a spell check to ensure error-free text. Dictionaries are available for over a dozen languages including English, French, German, Italian, Spanish, Dutch, Swedish, Danish, Croatian, Czech, Polish and Slovenian.

Client Log Files

The client application can easily log each action giving you an accurate record of everything that is happening behind the scenes. It’s perfect for debugging or even archiving. You can control the level of detail being logged, including options for recording script actions.

Unattended Builds

TrueUpdate fits seamlessly into your daily build process. Creating your update project every time you build your source code makes it easy to test early and often. Used in conjunction with design-time constants (e.g. DEFINE’s) and build response files, your TrueUpdate project can be kept up to date simply and automatically.

Works with Windows 95 and Up

Update systems created with TrueUpdate work just fine on every Windows operating system from Windows 95 to Windows 8 and beyond. 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

Who needs TrueUpdate?

Software developers, network administrators and end-users alike share in the benefits of TrueUpdate enabled software. Developers appreciate it for the control it gives them over software that has already been deployed. Network administrators benefit from improved security and better control of network nodes. End-users see TrueUpdate enabled software as an assurance of quality – a symbol that the developer is there to stand behind their product.

Any company who develops software applications or distributes data needs TrueUpdate. Any organization that needs to ensure its network is secure and updated with the latest patches needs TrueUpdate. Anyone who needs timely and secure synchronization of documents and files needs TrueUpdate.

Ensuring that everyone is using the most recent point release of a particular package makes good sense. It eliminates legacy technical support calls, and corresponding user frustration. It ensures that data is current. It also serves to maintain customer satisfaction. And that’s something everyone can appreciate.

What can you do with TrueUpdate?

Software products and network clients that have been TrueUpdate enabled can quickly and efficiently determine if they are out of date. Embedding TrueUpdate into a software product makes it extremely easy to manage, control and update "in the field". Likewise, deploying the TrueUpdate client to computer systems throughout your network gives you a fast and manageable way to ensure that each node is current with the latest patches, documents and data that your company requires.

What's wrong with traditional update methods?

One of the most serious problems with traditional update methods is that they require the users to do most of the work. The problem with relying on an update process that demands too much user involvement is obvious; the users might decide it isn't worth the hassle to keep their systems up to date. This results in a higher incidence of legacy support issues, more security holes and other related problems. Additionally, when users don't update, they don't benefit from bug fixes and product improvements. TrueUpdate helps solve all of these problems.

What is automated updating?

Automated updating is the ability of software to handle some or all of the update process so the user doesn't have to. The update process consists of all the steps required to determine whether a newer version exists for a given piece of software, as well as all the steps required to bring an older version up to date. Automating the update process allows software to keep itself current after it has been deployed to users.

How important is automated updating?

Today's rapid product cycles, security vulnerabilities and short turnaround times make it more important than ever to get new versions into the hands of users quickly and efficiently. The Internet has created a highly competitive market where users expect immediate results; the prize often goes to the company that reacts the most quickly to changes in user needs and perceptions. In order to streamline software deployment, it is becoming increasingly desirable for software authors to incorporate automated updating abilities into their software.

How does TrueUpdate 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. 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.

Why add TrueUpdate to your software application?

In a traditional release cycle, once your application or data files are released to customers, clients or other end-users, they are static, expensive and time-consuming to alter. However, once you add TrueUpdate to your application, you'll be able to easily update your product or data as often as you require.

From the developer’s point of view, when a new software release is available – perhaps a bug has been fixed – TrueUpdate makes it trivial to publish the changes and bring all of your users up to date. The next time the user runs the application, TrueUpdate will detect that a new release is available and take steps to handle it.

How easy is it to add TrueUpdate to an application?

As a self-contained executable, the TrueUpdate client can be integrated into your application in less than a day. While the actual time required depends on the amount of integration you desire and your level of programming knowledge, most developers should be able to complete the job in just a few hours. We even include sample source code for adding a "Check for Update" menu command and tips to get you going.

Alternatively, the TrueUpdate client executable can be distributed directly, rather than being embedded within an application. This allows the TrueUpdate client to be called manually from the start menu, from a shortcut on the user's desktop or automatically with system schedulers. This method of adding TrueUpdate to your application is as easy as installing a shortcut onto the user's system.

How does TrueUpdate impact technical support?

TrueUpdate allows your users to benefit quickly from any new features and bug fixes you develop, which in turn reduces the incidence of support calls. Keeping users up to date makes it easier to support them when incidents occur.

How will TrueUpdate 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 updating the software as easy as possible. Making it easy for users to update your software shows that you're committed to supporting it.

How does TrueUpdate 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 TrueUpdate, the task is virtually impossible. By installing the TrueUpdate client onto your networked computers, you’ll be able to quickly and effectively roll out whatever software you want throughout your organization. The client software can analyze the computer system, decide what is currently installed and then take whatever actions you determine are needed to bring that system up-to-date. It’s fast, easy and automatic.

I'm not a developer...do I still need TrueUpdate?

Absolutely! You don't need to be a software developer to benefit from TrueUpdate. As a stand-alone executable, the TrueUpdate client can be used to update all kinds of files. You could use TrueUpdate to distribute product catalogs to your sales teams, or to remotely configure system files across your corporate network. Price lists, help files, quarterly reports, internal support videos--TrueUpdate can help you keep anything up to date.

Does TrueUpdate actually install files?

With a full suite of file operations, including specialized actions to download, copy, delete, rename and even zip and unzip files, TrueUpdate may be all you need to install files onto a user's system. For situations requiring a more manageable and compartmentalized solution to file installation and patching, we’d recommend using Indigo Rose's Setup Factory and Visual Patch products. Used in conjunction with TrueUpdate, these products make up a complete and robust software deployment and management solution.


Chapter 1: The TrueUpdate Model

User's Guide - Chapter 1: The TrueUpdate Model

The TrueUpdate Model

Like any system that involves client-server interaction, updating software is a sophisticated process. It involves advanced technologies and protocols and rules that, without a clear and defined plan, would seem incredibly daunting to employ.

TrueUpdate is specifically designed to make the entire update process as simple to understand and as easy to accomplish as possible. Much of this is due to the unique update model that TrueUpdate employs. TrueUpdate provides the framework that makes it possible--in fact, easy--for you to build an update for your software.

Before you start working with TrueUpdate, however, it is important to understand the way TrueUpdate works.

What Does TrueUpdate Do?

At its simplest, TrueUpdate is an updater of software. It determines whether an update is available, downloads the required files, and then uses them to perform the update.

Anything that falls within that broad definition is possible with TrueUpdate. All of the details are in your control, from the specific methods used to detect the installed version, to the steps that are taken to actually update the software. An update can be as simple as making a subtle change to a registry key, or it can involve downloading and applying multiple patch files from a geographically selected download location.

Most commonly, however, TrueUpdate will be used to perform these basic functions:

• Determining the version that is installed

• Deciding whether an update is available

• Deciding whether an update is required

• Acquiring the appropriate patch file

• Applying the patch to update the installed version

Other Uses for TrueUpdate

The above steps describe the most common use of an updater like TrueUpdate. However, TrueUpdate is an incredibly flexible tool. In addition to handling the countless variations on the update process that are possible, TrueUpdate can be used to perform many other tasks--including some that are completely unrelated to updating software. For example, you could use TrueUpdate as a communications tool, automatically detecting and displaying a new "message of the day" from a central location. Or you could use it as a general development environment, taking advantage of its sophisticated system actions and wizard-like screens to build standalone configuration utilities. The possibilities are indeed limitless.

The TrueUpdate Client

The TrueUpdate Client is the client application that will actually perform the update process. It is generated when you build your TrueUpdate project. This is the "updater" that you will distribute to your users in order to provide the update ability.

In other words, the TrueUpdate Client is the program that does the work of your update. Everything in your TrueUpdate project--from the project settings that you configure, to the server-side scripts that you create--either directly affect how the TrueUpdate Client is built, or serve as instructions that define how it performs the update.

The TrueUpdate Client is a compact, self-contained application, without any external dependencies such as .Net, Java, or any other needlessly complicated technologies. It takes advantage of standard Internet protocols and encryption methods to perform the update process in a robust and secure way.

It’s also designed to be mindful of privacy needs. The TrueUpdate Client doesn’t require any information to be sent to the server at all--everything from the installed version detection to the decision about whether an update is required is handled entirely at the client end. This client-pull method completely avoids the privacy issues that revolve around other methods that require detailed information about the user’s system and installed software to be transmitted to a remote location.

Of course, TrueUpdate can still communicate with a remote location if you need it to; in fact, it has built-in actions to submit information to standard web scripts using both unsecured and secured transfer protocols. However, this functionality is entirely in your control; a TrueUpdate Client will never send anything to a server unless you specifically design it to do so.

The TrueUpdate Client is also designed to keep itself up to date. It does this by automatically downloading any updated versions of its client data or executable files that it finds at the TrueUpdate Server. (The latest versions of these files are included in the server configuration files that are uploaded to each TrueUpdate Server location.)

TrueUpdate Servers

A TrueUpdate Server is any location where the TrueUpdate Client can download the server configuration files that tell it how to perform the update. This can be a standard HTTP server, a standard FTP server, or even a folder on your local area network.

Note that this is completely independent of any specific hardware platform, operating system, or server software. TrueUpdate doesn’t lock you into any proprietary server technology. In fact, it doesn’t require you to run anything on a server at all.

All you need to create a TrueUpdate Server is a place to put your server configuration files where the TrueUpdate Client will be able to get them. "Creating" the server involves nothing more than uploading a handful of files and adding the new location in your TrueUpdate project settings.

For example, if you upload the server configuration files to your company’s web server, and add the location in your project settings, you’ve just created a TrueUpdate Server. Want another TrueUpdate Server for redundancy? Upload the files to another web server, or to an FTP server, or to a folder on your network. You could even copy the files to a USB key and pass it around the office--anywhere that your TrueUpdate Client can access the files is a valid TrueUpdate Server location.

Because TrueUpdate Servers use standard Internet protocols, you are free to take advantage of the full range of server technologies available to you. Whether your server is an old PC in your basement, or a fully load-balanced and distributed server farm in a high-security building, the choice of where and how to host your files is entirely up to you.

Note: For more information on TrueUpdate Servers, please see Chapter 6.

Server Configuration Files

Server configuration files provide the server-side component of the update process in TrueUpdate. This handful of files contain all the information the TrueUpdate Client needs in order to keep itself up to date and to perform the actual update of your software.

Specifically, the server configuration files allow each client to:

• Update its client-side data and executable files if newer versions become available

• Determine what version of your software is currently installed

• Determine whether an update is required

• Take the steps required to update the installed software if it is out of date

The server configuration files are generated whenever you build a project. They are completely project-specific--the server configuration files that you build in one project will only work with a TrueUpdate Client generated from that same project. In other words, TrueUpdate Clients and server configuration files from different projects are incompatible.

Note: TrueUpdate Clients are only compatible with server configuration files from the same project.

The Update Process

Here is a description of a typical update process in detail.

1. The TrueUpdate Client welcomes the user to the update by displaying an appropriate screen or popup dialog box.

2. The client then attempts to download the server configuration files from the first server in its list of TrueUpdate Servers. (By default, it will attempt to connect to each server location in the list until it succeeds.)

3. Once it connects to a server location, it checks to see if the location contains a newer version of the client data or client executable file. If it does, the client downloads the appropriate server configuration files (e.g. the .ts2 or .ts3 file, or both), and then restarts in order to use the new version of itself.

4. Assured that it is up to date, the client next downloads the server script and screens, which are contained in the .ts1 server configuration file.

5. After loading the server screens into memory, the TrueUpdate Client runs the server script.

6. The first function of the server script is to determine what version of the target software is currently installed on the user’s system. This version is generally referred to as the installed version.

7. Once the installed version has been determined, the server script compares it to a target version. The target version represents the desired version of the software--i.e. the version that the script was designed to update the software to.

8. If the above test determines that the installed version is already current, the server script informs the user that they already have the latest version, and then exits.

9. If on the other hand the test determines that an update is required, the server script proceeds with the actual update process. While the actual update method will vary from project to project, the most common method involves downloading a single executable patch file and then running that file with appropriate command line options.

10. If the patch file returns a value that can be used to determine whether it succeeded, the server script will usually check this value and then inform the user of the success or failure of the update.

11. If the patch file doesn’t return any such information, the server script will either wait for the patch to finish and then inform the user that the update process is complete, or simply exit silently and let the patch continue on its own.

Scripts

Scripts are a key component of TrueUpdate. In fact, the entire client-server interaction is scripted, and the built-in screens implement their functionality using scripts triggered by various screen events.

This is a very important feature, because it exposes the implementation to you for modification. In other words, the scripted nature of TrueUpdate makes it possible for you to completely control the behavior of your update.

A script is essentially a list of instructions for the TrueUpdate Client to follow.
Each script contains a sequence of commands, called actions, which work together to perform a specific task. A script can contain a single action, or any number of actions. These actions combine to form a series of steps that are performed sequentially, with one action following another. The sequence of actions can either occur in a direct and straightforward manner, or--by taking advantage of control structures like "if" and "while"--can incorporate sophisticated techniques such as decision-making, branching and looping.

Note: Scripts are ultimately just text documents that follow a specific syntax. The actions and control structures in a script are represented by specific keywords, which the TrueUpdate Client interprets as instructions that tell it what to do. You can edit these instructions as easily as you would edit any other text.

Script Tabs: Client vs. Server

Each TrueUpdate project contains two main scripts: a client script, and a server script. In the TrueUpdate development environment, these two scripts are represented by the Client Script tab, and the Server Script tab.

The scripts are divided according to where they are stored. The client script is built into the TrueUpdate Client application, and the server script is stored in one of the server configuration files.

Together, these two scripts implement the client-server interaction and control the entire update process.

The Client Script

The client script’s job is to introduce the user to the update, and download and run the server script.

Downloading the server script is done using the TrueUpdate.GetServerFile action. Since this action involves downloading files, it is usually called from a client screen (e.g. the Download Server Script screen) so that progress can be shown.

Once the server script is downloaded, it can be executed using the TrueUpdate.RunScript action.

The Server Script

The server script’s job is to determine whether an update is required, and then to actually perform the update--either by running a series of actions or by launching a separate installer or patch file.

Because it is downloaded each time your TrueUpdate Client connects to a TrueUpdate Server, you are free to modify the server script at any time--even after the TrueUpdate Client has been distributed.

This separation between the client and the server scripts is an essential feature of TrueUpdate. It allows you to adjust the update process for your software at any time, without any modifications to the client at all. In other words, it allows you to modify your update process without having to redistribute new clients to your users.

Screens: Client vs. Server

Screens are the individual windows that make up any wizard-styled update. When you navigate through an update by clicking the Next and Back buttons, you are navigating from screen to screen.

Note: Each screen has a number of events, with associated scripts that get executed when the corresponding events are triggered. By modifying these scripts you have full control over the functionality of the screens in your project.

Like the client and server scripts, the screens in your project are divided into two main areas. In the TrueUpdate development environment, these areas are represented by two screen panes, which by default are tabbed together in the upper right corner of the program window. There is one screen pane for the client-side screens, and one for the server-side screens.

The Client Screens

When you build your project, the screens on the Client Screens pane are packaged with the TrueUpdate Client and are accessible to the end user without having to download anything from the Internet. These screens cannot be updated without updating the client itself.

The Server Screens

The screens on the Server Screens pane are stored in a server configuration file. These screens are accessible to the end user only after the client has downloaded the server configuration files. Because the screens on the Server Screens pane are downloaded whenever the TrueUpdate Client connects to a TrueUpdate Server, you are free to change them after your client has been distributed.

Updating An Existing Client

The client script and client screens are stored within the client’s data file, which is normally distributed initially with your software.

Generally, it is preferable to write the client script in such a way that it does not need updating after the client has been distributed. If changes are made, the client will need to be restarted in order to update itself.

Of course, there may be an occasion when you need to add actions to your client script or to add another screen after your client has been distributed.

Not to worry; TrueUpdate has been designed to handle such cases. Every time your project is built, three server configuration files are generated. One of these files (the .ts1 file) contains the server scripts and server screens. The other two server configuration files contain the latest versions of your client data file (.ts2) and client executable (.ts3). This allows each client to automatically update itself if you have made changes to the client script and screens.

Here’s how it works: Whenever a TrueUpdate Client connects to a TrueUpdate Server in order to begin the update process, it first checks to see if the .ts2 and .ts3 files on the server are newer than the client’s current data file and executable. If either of the files is newer, the client downloads the new file, replacing the existing file with the new version. Remember that in order to replace either of these files, however, the client needs to restart itself; therefore, if at all possible, it is better to avoid updating the client script and client screens after the client has been distributed to your users.


Chapter 2: The Project Wizard

User's Guide - Chapter 2: The Project Wizard

The Project Wizard

Every journey begins with a first step, and TrueUpdate makes this step as painless as possible. With the built-in project wizard, creating professional product updates is as easy as filling in the blanks and clicking Next. This chapter will introduce you to the easy-to-use TrueUpdate project wizard.

Starting a New Project

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

A project is simply the collection of scripts, screens, settings and everything else that goes into building an update. For example, each project will contain the scripts and screens that will be built into the TrueUpdate Client application as well as those that will be contained in the server files. The settings for all of the scripts and screens in a project are stored in a single file, known as the project file.

When you start a new project, TrueUpdate’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 TrueUpdate program and start a new project.

1) Open TrueUpdate.

Use the Start menu to launch the TrueUpdate program.

You’ll find TrueUpdate under:

Start > Programs > Indigo Rose Corporation > TrueUpdate 3.0

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

The Welcome dialog appears whenever you run TrueUpdate. 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 TrueUpdate.)

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

3) Enter your project information and click Next.

First, the project wizard asks you for three pieces of information related to your project. Simply enter your company name and product name in the appropriate fields. Additionally, you may specify a unique server file encryption key; however, the randomly generated default key is unique to each project and is typically sufficient.

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) Select the Wizard style interface and click Next.

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

The most common update user interface is the default Wizard style. A Wizard style interface presents the user with a series of screens which 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 update. A silent update runs entirely in the background, and has no user interaction whatsoever.

The last option in this step allows your TrueUpdate Client to run silently until an update is available. Once an update is available, the client will continue in whatever style you have chosen (Wizard or Dialog).

5) Select a theme for your update, and click Next.

This step allows you to configure how your update will look. Once you’ve selected your project theme, click Next to proceed to the next step.

6) Select the languages you plan to support in your update and click next.

TrueUpdate supports multilingual updates. In this step, you can select which languages you want your update to support by checking them off. As well, you can select the default language to be used in the event that the user’s system employs a language you haven’t specifically accounted for.

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

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

Note: Only supported languages will appear in the language selector; you will only be able to select a language on a screen if that language was "checked" in the list of supported languages.

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

7) Select which download method your update will use, and click Next.

TrueUpdate supports a variety of file transfer protocols. This step allows you to specify which protocol your update will employ.

The first option is to use the standard hypertext transfer protocol (HTTP). This protocol was designed for accessing files on a web server from your local system. This is the same protocol that Internet Explorer uses, and is generally the easiest method to use. Since it uses port 80 by default, it’s also the most likely method to be allowed across a user’s firewall; chances are that if a user can browse the Internet from their computer, they’ll be able to run your update.

The second option is to use the secure hypertext transfer protocol (HTTPS). This is essentially a "secured" version of HTTP that uses the Secure Sockets Layer (SSL) to perform the data transfer in a more safeguarded fashion. It operates on port 443 by default.

Note: In order to use the HTTPS protocol, you must have a secure web server to connect to. You can’t use HTTPS to connect to a regular web server; you can only use the HTTPS protocol if your web server supports it.

The third option is to use the file transfer protocol (FTP). This protocol was designed for exchanging files over the Internet, and supports file transfers in both directions, i.e. downloading and uploading. (It is commonly used to upload web page files to the web server that will host them.) In order to transfer files to or from an FTP server, you must logon to it by providing a user name and password. Many FTP servers provide public access to their files by accepting a "guest" logon; this is usually referred to as "anonymous ftp." The FTP method transfers files over port 21 by default.

The fourth option is to copy the files over a local area network (LAN). This method is ideal if your update will be distributed within your organization, as transfer speeds are quite high. However, it cannot be used to download the configuration files from a remote site (over the Internet). To use the LAN transfer method, the client must have direct access to your network.

For this walkthrough, select the standard HTTP transfer method, and click Next.

8) Input your server's download settings, and click Next.

TrueUpdate needs to know the specifics of the server from which your client will download the configuration files.

Fill in the URL to the folder that will contain your TrueUpdate server files.

The Timeout setting refers to the amount of time in seconds that the TrueUpdate Client will wait with no reply before giving up on the server and returning an error.

The Port field allows you to specify a different communication port if your web server doesn’t use port 80 (the standard HTTP port). Use this field to specify which port your server is accessed by.

You can also use basic HTTP authentication to connect to your server, if required. This allows you an additional layer of security by requiring a valid username and password in order to download the server configuration files. If your web server supports basic HTTP authentication, select the "Use authentication" option and insert the authentication username and password.

9) Specify a server files prefix, and click Next.

This step allows you to specify the prefix that your server files will use. This is a useful step if you have multiple products and would like to host your products in the same folder on your web server.

10) Specify how TrueUpdate should transfer the files to your web server, and click Next.

For your convenience, TrueUpdate can automatically upload the server configuration files for you whenever you build your project. This feature can be a helpful time saver but is, of course, completely optional. You can always upload the configuration files to your TrueUpdate server locations on your own --by using your favorite FTP program, for example.

The first option allows you to take care of uploading the server configuration files on your own, separate from TrueUpdate, or to configure the upload automation later. (You can add automatic upload locations at any time on the Upload tab, which you can access by choosing Publish > Settings from the program menu.)

The second option will automatically transfer your files by FTP, and the third option will transfer your files by SFTP (secure FTP). These options are useful when you need to upload the files to a web server, as we will be doing in this walkthrough.

The last option performs a simple file copy and is useful if you selected LAN as your download method.

Since we chose to download the server files from an HTTP server earlier in this walkthrough, it would be convenient to have TrueUpdate upload the configuration files to that web server for us. Uploading files to a web server is normally done via FTP, so select the FTP option and click Next.

11) Configure your FTP server settings, and click Next.

This step allows you to specify where to upload the TrueUpdate server configuration files.

Note: Though we are uploading the server files via FTP, the client will access them via HTTP. Since HTTP is strictly a download protocol, we need to use a different protocol to upload the files to the web server.

In this step, you need to specify the full address of the folder where the server files need to be uploaded to. This will consist of the FTP server address and the full path to the folder on your FTP server. You can also configure the timeout of your FTP server and the port to be used when connecting.

Lastly, you must enter the username and password that is used to access the FTP server. Be sure to use a username with appropriate access rights, as the TrueUpdate design environment will be uploading files to the server.

The passive mode option is useful when connecting to an FTP server from behind a firewall. When you connect to an FTP server normally, the server attempts to open a second connection back to your computer. If you are behind a firewall, this connection will often fail. (Most firewalls object when external systems attempt inbound connections.) Using passive mode, the FTP server will wait for your computer to open both connections, thus avoiding the objectionable behavior. The FTP server must support passive mode connections in order for this method to work, but it is a widely supported option.

Once you have entered all of your information, click Next.

12) Select a version identification method, and click Next.

Since you are creating an update for an existing product, TrueUpdate needs to know how to determine which version of your software is installed on the user’s system so it can decide if a newer version is available.

There are basically three ways to determine which product version is installed. The first is to inspect the value of a registry key. This is an excellent option to choose if your installation program stored some kind of version-identifying value in the registry. For example, many installation programs create a registry key containing the version that is being installed so that other programs can easily determine the current version. This is a popular method supported by most installation tools. For example, Indigo Rose’s Setup Factory allows you to easily create and modify registry keys during an installation.

The second option is to use specific file information such as the date a file was last modified. In fact, many files such as exe’s and dll’s contain version information that can be read using this option. This method is useful if the installer stored no additional version information (for example, if the product didn’t use an installer at all). In that case, you may wish to use the version information stored in a primary file such as the software’s main executable (if it has one).

The third option is to read values directly from an INI file. This is similar to reading a value from the registry, but the value is retrieved from an INI file instead. The INI file would have either been included with the product or created when the product was installed. (Setup Factory is also capable of creating and modifying INI file entries.)

Note: Whether to store version information in the registry or in an INI file is largely a matter of preference. However, your TrueUpdate project needs to use the same method that was chosen for your installer. For example, if your installer stored the installed version in a registry key, your update won’t work if you tell it to get the version from an INI file.

There is a fourth option that allows you to skip this step for now. This is useful if you would rather configure this option later, or if, for example, you want to perform the update every time the update is run, regardless of the version currently on the user’s system.

For this walkthrough, select the File Information option and click Next.

13) Specify which file information will be checked, and click Next.

This step allows you to specify both which file and which attribute should be checked in order to determine which version of your software is installed.

There are five types of file information that can be checked:

File Version

The "file version" stored in the file. This is normally the version number of the file itself.

Product Version

The "product version" stored in the file. This is normally the version number of the product that the file belongs to.

Creation Date

The date and time when the file was created.

Modified Date

The date and time when the file was last modified.

CRC Value

The CRC value of the file. The CRC value serves as a digital "fingerprint" which can be compared to the CRC value of a known version of that same file in order to determine whether the two files match.

Select the Product Version option, and click Next.

14) Specify the target version, and click Next.

In the previous step, we decided to check a specific file for its product version. In this step, we will specify a value to compare that product version to. This essentially lets you specify the target version for your update--the version that you want to update the software to. This is the value that your TrueUpdate Client will compare the installed version to in order to determine whether a newer version is available.

You can click the Get File Version button to retrieve the version information from a specific file on your system. This allows you to quickly get the most up-to-date version information from your newest software.

15) Select an update method, and click Next.

This step controls how your software will be updated when the TrueUpdate Client determines that an update is available. There are two options. The most common method is to have your update download an executable patch file (or installer) and run it. Or, if you prefer, you can select a custom update method from a list of pre-defined templates.

Select the Single installer/patch file option, and click Next.

16) Select a download method for the patch, and click Next.

Before the client can run the installer or patch file, it needs to download it from somewhere. This step allows you to specify what method the TrueUpdate Client should use to download the file.

The same options exist as in step 7, where you specified what method to use to download the server configuration files. Select the HTTP method and click Next.

17) Specify your HTTP server settings, and click Next.

As in step 8, this step allows you to specify how the TrueUpdate Client will interact with your web server. Only this time, instead of specifying where the client can find its server configuration files, the settings determine where the client should get the executable installer or patch file that will actually update the installed software.

You must specify the exact path to your patch file, as well as the timeout and port to be used. Additionally, you may use a username and password to connect to the server if it supports basic HTTP authentication.

Once you have specified how TrueUpdate will connect to your web server, click Next.

18) Specify the download location and execution options, and click Next.

This step allows you to tell the TrueUpdate client what to do with the patch once it has been downloaded.

You must specify a location to download the patch to. Be sure to specify a location that the users will have write access to, or the TrueUpdate Client will not be able to save the file. If the users do not have sufficient access rights to create a file in that folder, the download will fail.

You also have the option of specifying command line arguments to use, and whether the TrueUpdate Client should wait for the patch executable to return before continuing. Also, if your patch executable returns a result code, you can specify a return code that indicates success.

19) Review your settings, and click Finish.

This step allows you to review everything you have configured before you create the project. Review the information presented, and either move back through the wizard to make any changes, or click Finish.

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


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 TrueUpdate’s sophisticated program interface. 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 TrueUpdate’s self-help resources, which are designed to answer any questions you might have while working with TrueUpdate as quickly and efficiently as possible.

Updating TrueUpdate

TrueUpdate has the built-in ability to check the Internet to see if there is an update available. In fact, this ability is the result of a TrueUpdate Client application, just like the ones you will build with TrueUpdate.

Before we start exploring the program interface, let’s use this feature to make sure you have the latest version of the program.

1) Choose Help > Check for Update.

The TrueUpdate Client application will open.

2) Click Next.

When you click Next, the TrueUpdate Client will connect to the Indigo Rose website and determine whether there is a newer version of TrueUpdate available for you to download. If there is, it will give you the option to download and apply a patch that will update your copy of TrueUpdate to the latest version.

Note: If you are running any Internet firewall software such as ZoneAlarm, it may ask you whether to permit the TrueUpdate Client to connect. You will need to allow the client to connect in order for the update to work.

3) If an update is available, click Next and follow the instructions to update your software to the latest version. Otherwise, click Close to exit the TrueUpdate Client application.

You will be alerted if an update is available. Simply follow the instructions to complete the update.

If an update is not available, just click Close to exit the TrueUpdate Client application.

Learning the Interface

Now that you know you are using the latest version of TrueUpdate, it’s time to get comfortable with the actual program interface.

1) Explore the TrueUpdate program window.

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

2) Check out the Script Editor.

The script editor takes up most of the program window. It is where you will edit the main scripts that determine what your project does. There are actually two script editors in this window--one for the client script, and one for the server script. You can switch between the client and server scripts by clicking on the respective tabs.

The script editor is a full featured code editor, including autocomplete, dropdown lists, and syntax checking.

3) Keep an eye on the Quick Help bar.

At the very bottom of the window is the quick help bar, which displays any quick help information available. For example, when working with an action in the script editor, the quick help bar will display the prototype for that action.

4) Take a peek at the panes.

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.

There are two panes to the right of the script editor. The top-most pane is actually a pair of panes that have been tabbed together: the Client Screens pane, and the Server Screens pane. Because these panes are tabbed by default, we often refer to them as the Client Screens tab and the Server Screens tab.

The client screens are distributed with the TrueUpdate Client application, and the server screens are stored in the server configuration files (which get hosted at your TrueUpdate Server locations). You can switch between the client screens and server screens by clicking on the appropriate tab.

Below the pair of screen panes is the Screen Preview pane. When a screen is selected on one of the screen panes, a preview of how that screen will look is shown in the Screen Preview pane.

5) Make the screen panes larger by dragging their window edges to the left.

You can resize panes by dragging their edges. In this case, you want to drag the part "between" the rightmost panes and the script editor...specifically, the little bit of window surface to the right of the script editor and to the left of the two screen panes and the Screen Preview pane. As you begin to drag the edge of a pane, a line will appear to show where the edge will move to when you release the mouse button.

You can also resize the screen and preview panes vertically by dragging the window edge between the two of them up or down. As one becomes larger, the other will become smaller, and vice-versa.

6) Double-click on the Screen Preview pane’s title bar to un-dock it.

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

When you un-dock the Screen Preview pane, it floats above the program window, and the screen panes expand to fill in the space that the Screen Preview pane left behind.

7) Drag the Screen Preview pane to the bottom of the screen panes to dock it again.

You can move panes around by dragging them by their title bars. As you move a pane, an outline shows you the general area where the panel will end up, and special ‘drop points’ appear to control where the pane will be docked. We want to put the Screen Preview pane back where it was originally. Drag the Screen Preview pane by its title bar around the design environment until the drop points appear. Then, drop it on the point that will re-dock it below the screen panes.

Tip: When you are dragging panes, the position of the mouse cursor is what determines where the pane will land. When moving panes to the drop points, the mouse pointer must be over the point for the screen to dock as you intend.

8) Unpin the Screen Preview pane, and then pin it again.

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

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

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

9) Turn on the Script Help toolbar.

Right clicking on the standard toolbar will bring up the list of available toolbars. Notice that only the standard toolbar is enabled by default. Click on ‘Script Help’ to enable the Script Help toolbar. This toolbar displays useful tips and information, and any other helpful tools relating to scripting.

You can turn on as many toolbars as you like, or disable them all. You can drag and drop toolbars around the interface similar to how you dragged panes around. Dragging a toolbar to the edge of the TrueUpdate window will dock it to that side. Dragging a toolbar to the middle of the TrueUpdate window will make the toolbar float above the interface.

Feel free to customize the design environment as you see fit. TrueUpdate is your tool, so go ahead and arrange it to fit the way you work.

Getting Help

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

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

1) Press the F1 key.

Help is only a key press away! TrueUpdate comes with an extensive online program reference with information on every action and feature in the program.

In fact, pressing F1 will, whenever possible, 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 action.

Note: You can also access the help system by choosing Help > TrueUpdate Help.

There are three ways to navigate the online help system and find the appropriate topic: use the table of contents, use the keyword index, or search through the entire help system for a specific word or phrase.

2) Close the help window and return to the TrueUpdate design environment.

To exit from the online help, just click the Close button on the help window’s title bar.

3) Choose View > Help to open the Help pane.

You can also open the help file inside a pane, right in the TrueUpdate design environment. This is especially useful when you’re working on scripts and want quick access to the help topics for the actions you’re working on.

4) Select the Client Script tab, and click on the Screen.Show action.

When you click on an action in the script editor, notice that the Help pane automatically displays the help topic for that action.

As you are working on your scripts, the Help pane will automatically display the help topic for any action that you click on. It will also automatically display the help topic for an action as you’re typing it into the script editor. (In other words, if you typed "Application.Exit" into the script editor, the Help pane would automatically show you the help topic for the Application.Exit action.)

5) Choose View > Help again to close the Help pane.

Choosing View > Help will close the Help pane if it is currently open.

6) Choose Help > User Forums.

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

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

7) Close your web browser and return to the TrueUpdate design environment.

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

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

8) Choose Help > Technical Support > Support Options.

This takes you to the TrueUpdate web site, where a variety of online technical support resources are available to you, including a large 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.

9) Close your web browser and return to the TrueUpdate design environment.

When you’re done browsing the technical support information, return to the TrueUpdate design environment to continue with this chapter.

Setting Preferences

There are a number of preferences that you can configure to adjust the TrueUpdate design environment to suit your work style. Let’s have a look at some of them.

1) Choose Edit > Preferences.

This will open the Preferences dialog, where all of TrueUpdate’s preferences can be found.

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

2) Click on the Document category.

The Document preferences allow you to change settings that affect the project file. For example, you can configure the auto-save feature that can automatically save your project file as you’re working on it to avoid any accidental loss of data. You can also configure the number of undo/redo levels, and choose either to use the project wizard to create new projects or to simply start with a 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" and go back further in your project if you change your mind while you’re working.

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

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

The Folders category allows you to specify the locations of various folders that are used by the project. For example, you can specify the location where project files are stored, and specify the default output folder where your update files will be published to.

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

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

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


Chapter 4: Introduction to Scripting

User's Guide - Chapter 4: Introduction to Scripting

Introduction to Scripting

Scripting is the art of creating and modifying a sequence of actions that work together to perform a specific task.

Actions are among the most important features in TrueUpdate. They are what you use to control the functionality of your update, with virtually limitless possibilities. Each action is a specific command that tells your TrueUpdate Client to do something, such as downloading a file, showing a screen, or modifying the Registry.

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

In this chapter, we’ll introduce you to the basics of scripting in TrueUpdate.

What Are Scripts?

A script is a sequence of actions that work together to perform a specific task. It can include a single action, or any number of actions. The simplest scripts comprise a basic series of steps, with one action following another in a direct and straightforward manner. More advanced scripts take advantage of control structures like "if" and "while" to incorporate sophisticated techniques such as decision-making, branching and looping.

Scripts are ultimately just text documents that follow a specific syntax. The actions and control structures in a script are represented by specific keywords, which the TrueUpdate Client ultimately interprets as instructions that tell it what to do.

Note: Scripts are a key component of TrueUpdate. For example, the entire client-server interaction is defined by the script that is entered on the Client Script and Server Script tabs.

What Are Actions?

Actions are what you use in TrueUpdate when you want to get something done. They are specialized commands that your TrueUpdate Client can perform at run time. Each action is a short text instruction that tells the client to do something--whether it’s to download the server configuration files, show a screen, open a document, 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 period or "dot," like so: File.Run, Registry.GetValue. The text "File.Run" essentially tells TrueUpdate 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."

It is worth noting that the many screen types available to you in TrueUpdate actually use actions to accomplish their tasks. In fact, if you want to modify a screen’s built-in functionality, you can do so simply by editing the screen’s actions. Because of TrueUpdate’s scripting engine, the power is in your hands!

The Script Editor

The script editor is where you create and edit your scripts in the TrueUpdate design environment. It essentially functions like a text editor, allowing you to type the actions and other scripting elements that you want to use.

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

It also has a built-in action wizard, which provides an easy dialog-based way to select, create, and edit actions without having to type a line of script.

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

Script Tabs and Screen Events

The script editor has two visible interfaces, depending on whether you are adding actions to script tabs or screen events.

The script editor is functionally the same in both places; the only difference is in how you access some of its programming features. The screen event tabs have built-in buttons that allow you to access the most common features of the script editor. The script tabs have no integrated buttons; instead you can access the features via the program menu and toolbars. In both cases, however, you can access the features by using the right-click menu.

Programming Features

The script editor provides many powerful features that make it a useful and accessible tool for programmers and non-programmers alike. Along with the action wizard (covered later under Using the Action Wizard), the four most important features of the script editor are: syntax highlighting, intellisense, quick help, and context-sensitive help.

Syntax Highlighting

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

Note: You can customize the colors used for syntax highlighting via the script editor settings. The script editor settings are accessed on screen event tabs via the advanced button: Advanced > Editor Settings. On script tabs it can be accessed from the program menu by choosing Edit > Advanced > Editor Settings.

Intellisense

Intellisense is a feature of advanced programming environments. It 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 with various intended meanings. In TrueUpdate, intellisense manifests itself as two features: autocomplete, and the autocomplete dropdown.

Autocomplete is the editor’s ability to automatically complete keywords for you when you press Tab. As you type the first few letters of a keyword into the script 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 as to 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, you can make a drop-down list appear containing the names of all the available actions, constants and global variables. Choosing one of the listed items and pressing Tab or Enter will automatically type the item into the script editor 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 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.

Quick Help

Once you’ve typed something that the script editor recognizes as the name of an action, quick help is automatically displayed. Quick help is essentially a "blueprint" for the action. It lists the names of the action’s parameters, and indicates what type of value is expected for each one. For example, in the case of a Screen.Jump action, the quick help looks like this:

Screen.Jump(string ScreenName)

This quick help indicates that the Screen.Jump action takes a single parameter called ScreenName, and that this parameter needs to be a string. Strings need to be quoted, so if you wanted to jump to a screen named Finish, the full action would have to be typed exactly like this:

Screen.Jump("Finish");

On screen events, the quick help is located towards the bottom of the properties window. When you’re working on script tabs, it can be found on the status bar at the bottom of the program window, or on the optional Script Help toolbar. (You can enable the Script Help toolbar by choosing View > Toolbars > Script Help.)

Context Sensitive Help

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

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

Note: The context sensitive feature is only available when the script editor recognizes the action that the cursor is on. It is easy to know when this is the case; when the script editor recognizes an action, the action’s template appears in the quick help.

Client Script

The Client Script tab is a script editor located on the main development window. It contains the script that runs as soon as the TrueUpdate Client application is started. This script is generally referred to as the client script.

Generally the client script should contain any actions needed to initialize and initiate the update process.

A typical client script will introduce the user to the update and then download the server configuration files. In fact, the main function of the client script is to download and run the server script, which is contained in the server configuration files.

Tip: While you’re working on the script tabs, you can access all of the script editor features under the Edit and Script program menus.

Server Scripts

The Server Script tab is another script editor located on the main development window. It contains the script that is hosted at the TrueUpdate Server locations. This script is generally referred to as a server script.

The purpose of a server script is to determine whether an update is available, and to actually perform the update--either by running a series of actions, or by launching a separate installer or patch file.

Multiple Server Scripts

TrueUpdate actually supports multiple server scripts, each represented by a separate tab on the program window. Every project begins with a single "main" server script, represented by the Server Script tab.

For larger projects, you may want to divide your actions into multiple server scripts in order to make the project easier to maintain. TrueUpdate allows you to add as many additional server scripts as you need in order to facilitate organizing your code.

The server scripts that you add are treated just like the main server script. In fact, the contents of all the server scripts are stored in the same server configuration file, and they are all downloaded together by the TrueUpdate.GetServerFile action. Just as you would run the main server script, you can run any individual server script using the TrueUpdate.RunScript action.

Tip: Use multiple server scripts to implement "branching" in different situations. For example, if your TrueUpdate Client needs to perform different steps in order to update different versions of your software, you could create a separate server script for each version, and then use the TrueUpdate.RunScript action to call the appropriate script tab from your main server script once the installed version is detected.

Designed For Easy Modification

The server scripts are stored together in one of the server configuration files, which is downloaded by an action in the client script. Because they are downloaded each time your TrueUpdate Client connects to a TrueUpdate Server, you are free to modify the server scripts at any time--even after the TrueUpdate Client has been distributed.

This separation between the client and the server scripts is an important feature of TrueUpdate. It allows you to adjust the update process for your software at any time, without any modifications to the client at all. In other words, it allows you to modify your update process without having to redistribute new clients to your users.

Note: The server scripts are normally what you will modify each time a new version of your software is released (or whenever you need to update your software).

Screen Events

Every screen has a number of events associated with it. These events are "triggered" when something happens to the screen. For example, every screen has an On Preload event that is triggered just before the screen is displayed.

For every event that a screen supports, there is a separate tab on the screen’s properties dialog. Each tab contains a script editor, where you can edit the script that will be executed when the corresponding event occurs.

When you add an action to a screen’s event tab, you are in effect adding the action to that event. At run time, when the event is triggered, all of the actions on the event tab are performed in sequence from top to bottom. In other words, TrueUpdate "runs through" the script for that event. This happens each time the event is triggered.

For example, to make something happen immediately before a screen is displayed, you would add an action to the screen’s On Preload event. To make something happen when a screen’s Next button is clicked, you would add an action to the screen’s On Next event.

Screen events are triggered either by the controls on the screen or by the screen itself. They can be used for navigation (e.g. moving to the next screen), to change what is displayed on the screen (e.g. updating progress text), or to perform the task required of the screen (e.g. downloading a file).

Note: A control is an "object" on a screen that serves a specific purpose, such as receiving mouse clicks, displaying text, or providing a checkbox. Most screens contain several controls. You can think of the controls as the different screen "parts" that allow the screen to do what it does. For more information on controls and which controls exist on the various screen types, please consult the help file.

Using the Action Wizard

The action wizard is a dialog-based way for you to add actions in the script editor. It is designed to guide you through the process of selecting your action and configuring its parameters.

Tip: Even if you prefer typing actions directly into the script editor, don’t disregard the usefulness of the action wizard. It is an excellent way to add an action when you aren’t familiar with its parameters and the range of values it accepts.

While in a script editor, you can launch the action wizard by pressing Ctrl+W, or by right-clicking and choosing Action Wizard from the context menu.

Note: The action will be added at the current location of the cursor, so take care where you click or right-click before launching the action wizard.

Adding Actions

Here is a brief example that shows how easy it is to add an action. It illustrates how to display a popup dialog with a message on it by adding a Dialog.Message action to the Client Script tab.

1) Start a new project and click Cancel when the project wizard appears. Make sure the Client Script tab is selected.

To start a new project, either start TrueUpdate and click "Create a new project" on the welcome dialog, or choose File > New Project from the program menu. When the project wizard appears, click Cancel to skip the wizard and go straight to the design environment.

Note: Normally you will want to use the project wizard in order to base your project on a completed structure; however for this example it is easier to start with an almost blank project.

Make sure you have the Client Script tab selected and not the Server Script tab. (You can select the Client Script tab by clicking on it.)

2) Comment out the Screen.Show action by adding two dashes (--) at the start of the line.

Before we continue, let’s disable the default client script’s Screen.Show action so it won’t interfere with this example.

Any line in a script that begins with two dashes is treated as a comment. Comments aren’t executed; they are typically used to add helpful notes and explanations to your code. For example, you’ll notice that the first four lines of the Client Script already have comments describing what the Client Script does.

When you add two dashes to the start of the line that has the Screen.Show action on it, the line turns green, the default color for comments in the script editor. Adding the two dashes turned the line into a comment. This effectively causes TrueUpdate to ignore that line completely.

You can add two dashes to the start of any line of code to "turn it off" temporarily. Turning a line of code into a comment is known as "commenting out" the code.

Tip: You can "uncomment" a line that is currently commented out by simply deleting the two dashes. Removing the dashes reverts the line to its former "active" status; it is no longer a comment.

For the purposes of this example, we don’t want the client script to display any screens; instead, we will be displaying a message in a popup dialog.

3) Place the cursor on the last line (line 8) and choose Script > Action Wizard from the program menu. When the action wizard appears, switch to the Dialog category and click on the action called Dialog.Message.

The action wizard will walk you through the process of adding an action to the client script. 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 help file.

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

Parameters are just values that get "passed" to an action. They tell the action what to do. For instance, in the case of our Dialog.Message action, the action needs to know what the dialog’s window title and message should be. You provide this information to the action in its first two parameters.

The first parameter lets you specify the title of the dialog. This it the text that will appear in the dialog window’s title bar.

The second parameter lets you specify the message that will be displayed on the dialog itself.

For now the other parameters are not important, but you should take some time to look at them and their options. (TrueUpdate will automatically fill the other parameters with appropriate default values.)

For now, change the title to:

"TrueUpdate"

and the text to:

"Message from Chapter 4!"

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

Once you’ve set the action’s parameters, click the Finish button to close the action wizard. The Dialog.Message action will appear on the Client Script tab.

Note that the parameters you provided are listed between parentheses after the action’s name. The parameters are in the same order as they appeared in the action wizard, separated by commas.

5) Build the project and run the TrueUpdate Client. When the client starts, you should see the dialog created by the Dialog.Message action.

Start the publish wizard by choosing Publish > Build from the program menu. The default settings should suffice, so click the Next button to show the list of upload locations (which can be ignored for this example) and then click the Build button to start the build process.

Once the build has completed successfully, make sure the "Open output folder" checkbox is selected, and click the Finish button.

Once the output folder appears, double-click on the client executable to launch it.

You should see a dialog message box.

This popup "message box" is the result of the Dialog.Message action.

Click OK to close the message box and allow the TrueUpdate Client to exit.

Editing Actions

There are two ways that you can modify an existing action: you can either edit the action’s text directly in the script editor, just like you would edit text in a word processor; or you can use the Action Properties dialog.

The Action Properties dialog is similar to the action wizard, but instead of walking you through choosing a category, it takes you straight to the part where you modify the action’s parameters.

The easiest way to bring up the Action Properties dialog is by double-clicking on the action. Or, if you prefer, you can place the cursor within the action and either press Ctrl+E, or right-click and choose Edit Action from the context menu.

Tip: You can tell that the cursor is within an action when the action’s function prototype appears in the quick help.

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

1) Double-click on the Dialog.Message action to bring up the Action Properties dialog.

First, make sure the Client Script tab is selected. You should see the Dialog.Message action created in the previous topic.

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

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

To change the Type parameter, first click on the parameter field, then click the select button at the right edge of the parameter field and choose MB_OKCANCEL from the drop-down list.

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

These changes 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 you made now appear in the script editor.

Constants

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

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

When you run the TrueUpdate Client, a dialog will pop up. This dialog is created by the Dialog.Message action on the Client Script tab.

Notice that there is no longer an "information" icon on the dialog, and there is now a Cancel button next to the OK button. This is a direct result of the changes that you made to the action’s parameters.

Getting Help on Actions

You can get help on actions in a variety of different ways in TrueUpdate. For example, when you’re using the action wizard, text is displayed at the bottom of the dialog describing the current action or parameter that you have selected. Additionally, quick access to the help file is provided in the form of a blue text link that you can click on to receive context sensitive help for the action.

In the script editor, the current action’s function prototype is displayed in the quick help field--either on the Script Help toolbar, in the status bar, or directly on a screen’s event tab. In the case of the Script Help toolbar and the event tabs, there is even a help button next to the quick help field that will open the help file directly to that action’s help topic.

You can press the F1 key at any time while working in the script editor to open the TrueUpdate help file. The help file is especially useful when you’re working with actions. It contains a wealth of information on each action, including an overview topic with detailed information about each parameter, and a topic providing one or more working examples for that action.

The overview topic for an action will provide you with the function prototype, which serves as a definition of the action showing what (if anything) the action returns, along with the action’s parameters and their types.

A function prototype 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 default values.

You can click on any part of the function prototype in the help file to learn more about that part and its particular purpose.

Includes

An include is any external script that can be "included" in your project. Also known as a script file, an include is simply an external text file that contains a valid TrueUpdate script. By convention, these text files usually have a .lua file extension.

You can add script files to your project on the Includes tab of the Resources dialog, which can be accessed by choosing Project > Includes.

All of the files listed on the Includes tab are stored in the client data file when you build your project. Note that this means adding or removing script files will result in a change to your TrueUpdate Client application.

Script files are very similar to script tabs in TrueUpdate except that instead of the script being kept in the project, it is stored in an external text file.

Note: All of the script editors in TrueUpdate have the ability to export their script to an external file. To save a script from the script editor, simply right-click and choose Advanced > Export from the context menu.

Script files are very useful if you need to share important and complex code between a variety of different projects. By keeping the common code in a single location, your projects will be easier to maintain.

This is more advantageous than simply copying and pasting scripts between projects. Having duplicated script in multiple projects can mean duplicated effort if you want to make changes to the script in all of the projects (e.g. if you discover a bug). For instance, when two projects contain copies of a script, you have to edit both projects in order to make the same changes to both scripts.

Using an external script file gets around this issue, by allowing multiple projects to share the same script. When using an external script file, each project does not contain a copy of the script; rather, each project references the same script. If you find an error or want to change any of the code, you do not have to edit the script in each project; you simply have to edit the script in the external file. Since each project references the same file, you know that the next time you build a project, it will be using the new script.

Using external script files allows you to maintain your script in a single location: the script file. For this reason, it’s a good idea to use includes whenever you want to share scripts between projects.

Plugins

Plugins are actions that are "added on" to the TrueUpdate program. They are independently developed and distributed and can be integrated into your projects to extend their functionality. You can obtain plugins developed by Indigo Rose as well as those developed by third parties.

Any available plugin can be enabled or disabled in your project on the Plugins tab, which you can access by choosing Project > Plugins.

Note: Only plugins that are installed in the Includes\Plugins folder within the TrueUpdate program directory will be available on the Plugins tab.

To enable a plugin in your project, simply place a check mark in the checkbox next to its name on the Plugins tab. Only plugins that are enabled on the Plugins tab will be available in your project.

Once you have enabled a plugin in your project, all of its actions become available to you in the script editor and action wizard. You can even access the plugin’s help file in the same way that you would access the help for built-in actions.

Note: Since there is some overhead in terms of file size, it is recommended that you only include plugins that are needed by your update. If you do not place a check mark beside a plugin, it will not be included in the TrueUpdate Client and will not take up any extra space.

For information about a particular plugin’s features and how to use them, refer to the plugin’s documentation. You can access a plugin’s documentation from the Plugins dialog by selecting the plugin, clicking the About Plugin button, and then clicking the Plugin Help button on the About Plugin dialog.

Tip: The More Plugins button on the About Plugin dialog is an easy way to see what plugins are currently available on the Indigo Rose website. Clicking this button will take you directly to the TrueUpdate plugins area of the Indigo Rose website.

Where to Go from Here

Now that you’ve been introduced to the basics of scripting, you’ll probably want to learn more about this important feature of TrueUpdate. Fortunately, there are several resources available to you.

The Scripting Guide

Chapter 11 of this user’s guide is a crash course on the scripting language. It covers the basic syntax of the scripting language, and more advanced topics such as looping and functions.

The Project Wizard

The scripts that are generated by the project wizard are excellent real-world examples for you to follow. They were designed to serve as best-practice examples, and include full comments making them easy to follow despite their sophistication. Try choosing different settings in the project wizard, and see how it changes the script as a result.

Project Templates

When you reach the "Update Method" step of the project wizard, you are given the option to use a single installer/patch file, or a custom method. If you choose the custom option and click Next, you will be presented with a list of project templates to choose from. These project templates also contain excellent real-world examples of scripting. Like the other project wizard scripts, they are also fully commented.

Sample Projects

TrueUpdate comes with a number of sample projects that demonstrate very specific update situations. In addition to being good starting points for your own projects, these sample projects contain customized scripts and screens that you will not find in the generic scripts that the project wizard generates.

The sample projects are located in a "Samples" subfolder within the Program Files folder where TrueUpdate was installed.


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 update. The user interface is the first thing your end users will see when they run your update. It also serves as a bridge between the information that the user has and that the update wants. Having an easy to use yet fully functional user interface is something that all users of TrueUpdate 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 update 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, they are interacting with the user interface.

The basic elements of the user interface are:

• Screens

• Themes

• 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. Screens are where your end user will actually interact with the update. They allow you to provide important information (such as changes to system requirements) and allow your user to make decisions (such as locating the product to be updated).

Tip: It is possible to create an update project that doesn’t use screens for its interface. For example, you can use individual popup "dialogs," or you can have your update remain "silent" and not show any interface at all. However, the most common and most attractive interfaces take advantage of TrueUpdate’s screens.

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

Tip: You can think of the screens in your project as steps in a wizard that walk your user through the process of updating their software.

In general, each screen performs a single task, such as showing a welcome message or letting the end user select which product to update. If you want to perform a major update task, chances are you will need a screen to do so.

The Screen Panes

The two screen panes are where you will configure all of the screens that are used in your project. By default, these two panes are tabbed together in the upper right hand corner of the program window.

There is one screen pane for client-side screens, and one for server-side screens. Since they are tabbed together by default, you can access either pane by clicking on the appropriate tab.

From the screen panes, you can add and remove screens and screen lists, as well as adjust the order of screens in your project. You can also import and export languages for individual screens.

Client Screens

When you build your project, the screens on the Client Screens pane are packaged with the TrueUpdate Client and are accessible to the end user without having to download anything from the Internet. These screens cannot be updated without updating the client itself. Whenever the TrueUpdate Client detects a newer version of itself on the server, it will update itself automatically; however, this self-update process requires the client to restart.

In order to make the update process appear as seamless to the user as possible, it is preferable to avoid unnecessary changes to the client screens after the client has been distributed to your customers. For this reason, you should only include screens on the Client Screens pane that will be used by the client script and that need to be shown before the server script has been downloaded.

Examples of typical client screens are:

• Welcome

• Download Server Script

• Download Server Script Failed

• Enter Password

Server Screens

The screens on the Server Screens pane are stored in a server configuration file. These screens are accessible to the end user only after the client has downloaded the configuration file--in other words, after the server script has been downloaded. This generally happens as the result of a TrueUpdate.GetServerFile action, which typically occurs every time the TrueUpdate Client is run.

Because the screens on the Server Screens pane are downloaded along with the server script, you are free to change them after your client has been distributed. Changes to the server script and server screens do not require the client to restart; any such changes will appear perfectly seamless to the user. In fact, you could completely replace all the server screens and the user would have no indication aside from the fact that this time, different screens are shown.

Examples of Server Screens are:

• Update Available

• Update Successful

• Download File (HTTP)

• Already At Target

Screen Lists

All screens in your project are organized into screen lists. The purpose of screen lists is twofold: they provide a way to group screens together, and they allow you to define separate sequences of screens.

A typical screen list will contain a sequence of screens that work together as a unit. For example, you might want to group all of the screens that deal with downloading your patch files within one screen list. This allows you to treat those screens as a single unit. Using a single Screen.Show action, you can show the list, and the screens within that list will display sequentially.

Note: The Screen.Show action takes two parameters: the name of a screen list, and the name of a screen within that list. If you omit the second parameter, the action will begin showing the first screen in the list, and only "return" once it reaches the last screen in the list.

In general, the order in which screens appear within a list on the screen pane will be the order in which they appear during the update. 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 appear last.

To change the order of your screens, simply select a screen in the list, then click the Up or Down button to place it in the desired location in the list.

Tip: You can use the Screen.Show action to show screens in the middle of a list by specifying which screen to start at. In this case, the screens would be displayed sequentially from that point forward. This can be useful if you want to "skip" some of the initial screens in a list in specific circumstances.

Adding Screens

Adding a screen to your project is easy. Simply select the screen list that you want to add it to, and click the Add button at the top of the screen pane. Note that screens can only be added to screen lists, and cannot exist on their own; a screen cannot be added until there is at least one screen list to add it to.

Note: To add a client-side screen, ensure that the Client Screens tab is selected. To add a server-side screen, ensure that the Server Screens tab is selected.

Clicking the Add button brings up the screen gallery where you can select from a variety of screen types. Once you’ve selected the type of screen you want, simply click OK to add it to the screen list.

Tip: Most of the screens in the screen gallery contain default scripts for their events. If the default behavior of a screen doesn’t suit your needs, remember that you can customize it by modifying the default scripts.

Removing Screens

To remove a screen from your project, simply select it on the screen pane and click the Remove button, or press the delete key.

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

Editing Screens

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

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

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

Showing Screens

At run time, only screens that are explicitly shown by your script are presented to the user. In order to show a screen, you must use a Screen.Show action. This action takes two parameters: the name of a screen list, and (optionally) the name of a specific screen in that screen list.

For example, to show the first screen in a screen list, you would use the Screen.Show action and specify the name of the screen list you wish to show:

Screen.Show("List01");

The above action would show the first screen in the list named List01. Assuming each screen in that list had a Screen.Next() action in its On Next event script, each screen in that list would be shown in sequence as the user clicked the Next button until the end of the "List01" screen list was reached.

Alternatively, you can specify a starting point within a list by indicating which screen should be shown first:

Screen.Show("List01", "Screen04");

The above action would show Screen04, and (once again assuming the screen handles the On Next event normally) every screen succeeding it in List01.

Note: You can only show the screens on the Server Screens tab after the server configuration files have been downloaded using the TrueUpdate.GetServerFile action. Attempting to show a server screen without first getting the server configuration files will result in an error.

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 depending on the screen type): 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 TrueUpdate help file.

Attributes

The Attributes tab contains settings that are common to all screens. The only difference that you will find between the Attributes tabs of different screen types is that Attributes tabs for progress screens lack options for the Next, Back, and Help buttons. This is because these buttons don’t exist on progress screens.

In general, 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, you might feel that a particular 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. Note that 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 and events, please see the help file and Chapter 4.

The Language Selector

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

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 TrueUpdate 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. "TrueUpdate"). 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 before the screen is displayed, so instead of seeing %ProductName% on the screen, the end user will actually see the name of your product that you entered in the project wizard, or on the Session Variables tab of the Project Settings dialog.

Session variables are also used to store return values when screens or controls need them.

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 user takes through the screens in your update. The user navigates forward through various screens by clicking the Next button, and backward through the screens by clicking the Back button.

Screen navigation is basically a linear path from the top screen in a screen list to the bottom screen. Generally, the order of your screens in a screen list 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.

Note: The user cannot normally move between screen lists using the navigation buttons. If you want them to be able to move back into a previous screen list, or forward into the next screen list, you will need to use additional Screen.Show actions in your script. For example, when Next is clicked on the last screen in a screen list, TrueUpdate does not display the next screen list, but instead returns back to the location where Screen.Show was called from. In order to show the next screen list, you would need to follow that first Screen.Show action with a second one.

How Screen Navigation Works

In its simplest form, screen navigation is when the user moves forward or backward through the update by clicking the Next and Back buttons. By default, this moves the end user down or up through the screens in a screen list.

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 necessary, you can modify or override the default behavior of any screen by editing or replacing the default actions with your own. 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 user down a screen list from the top to the bottom; the Back button moves up through the screen list; and the Cancel button stops the user’s navigation by canceling the entire update.

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

The two options for the visibility state are self-explanatory; they make the button either visible or invisible. The two options for the enabled state make the button enabled or disabled. If a button is in the enabled state, it looks and functions like a normal button; it will depress when the user clicks on it, and the text is displayed in its normal color (usually black). When a button is in the disabled state, however, it will not respond to the user’s mouse, and is typically drawn in less prominent gray shades (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 update. When an event is triggered (or "fired"), any actions that are associated with that event are performed. Note that an event must be triggered in order for its actions to be performed. If an event is not triggered, the actions associated with it will not be performed.

Each event represents something that can happen while your update 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 screens 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 when a control on the screen fires a control message (for example, when the user clicks on a button, or when an item is selected in a list box)

Navigation Actions

There are seven navigation actions available to you in TrueUpdate: Screen.Back, Screen.End, Screen.Jump, Screen.Next, Screen.Previous, Application.ExitScript, and Application.Exit. The most common of the seven actions 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 in the update. 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 update to the previous screen. To implement this behavior, a Screen.Back action needs to be executed when the On Back event is fired.

Note: The Screen.Back action moves backward through the screen history in the same way that a Back button does in a web browser: it sends you "back" to the previously viewed screen. To move up one screen in the screen list, use the Screen.Previous action, which sends you to the previous screen in the list.

In certain situations, simply moving down a screen list is not the appropriate behavior; instead, jumping to a specific screen in the list is necessary. You can accomplish this by using a Screen.Jump action. If the goal is to jump to the next list in the update, first a Screen.End action can be used to jump past all of the screens in the current screen list, and then a Screen.Show action can be used to show screens from the next list.

To interrupt screen navigation--which usually occurs when the Cancel button is clicked--you can use an Application.ExitScript action. The Application.ExitScript action immediately exits from the current script--essentially skipping any actions that follow and going straight to the end of the script. In other words, it forces the immediate interruption of the current screen event.

The Application.Exit action goes one step further: it causes your entire update to exit as soon as the action is performed. In other words, it not only stops the current script, it stops the entire TrueUpdate Client application.

Tip: You can find detailed information on these actions in the help file.

Screen Controls

A control is an "object" on a screen that serves a specific purpose, such as receiving mouse clicks, displaying text, or providing an option in the form of a checkbox, radio button, etc. Most screens contain several controls. You can think of the controls as the different screen "parts" that allow the screen to do what it does. In other words, controls are the parts of a screen that your users directly interact with.

Note: Most controls are designed to display information to the user or receive the user’s input.

TrueUpdate provides a number of actions that allow you to get and set the properties of the controls on a screen. You can use these actions to change the information that is displayed on a control, or to retrieve the information that the user provided.

For example, if you need to determine whether a checkbox is selected, you can use a DlgCheckBox.GetProperties action to investigate the control’s "checked" property.

Similarly, if you wanted to change the contents of a list box according to the user’s input on a previous screen, you could modify the list box’s items using actions like DlgListBox.AddItem and DlgListBox.DeleteItem.

Tip: The control-related actions in TrueUpdate begin with "Dlg," which is short for "Dialog." In programming terms, TrueUpdate’s screens are implemented as dialog windows. The "Dlg" prefix was chosen for its familiarity to Windows programmers.

You can also use actions to programmatically show and hide controls, or enable and disable them. For example, you could hide a button on a screen if the user’s input on the previous screen made that button unnecessary. Or you could make one checkbox only become enabled after the user selects another checkbox, essentially making the second checkbox a "sub-option" of the first.

Note: For more information on screen controls and the related actions, please consult the help file.

Screen Layout

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

Note: A control can be thought of as any visible element 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 TrueUpdate are divided into three basic parts: the header, the body and the footer.

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

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

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

Banner Style

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

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

The top banner style has a long thin banner (or "header") across the top of your screen. 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 user.

The top banner style also supports an image that will be placed on the right hand side of the banner. The image is drawn starting from the upper right corner and extending towards the lower left. If the top banner image is taller than the banner area, it will extend down into the body of the screen. In fact, the top banner image can be as large as the body and cover the whole screen. Any area of the top banner that is not covered by the image will be painted with a color according to the project theme.

The side banner style has an image that runs down the left side of the screen, forming a vertical banner alongside the body.

The side banner image is drawn in the upper left corner of the screen, starting from the upper left and extending towards the lower right. Like the top banner image, it can be larger than the banner area and extend into the body.

Tip: For more detailed information on how the screens in TrueUpdate are drawn, and for an example of how to use the side and top banner images to create interesting backdrops for your screens, see How Screens Are Drawn in the help file.

Dynamic Control Layout

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

Dynamic control layout means that controls will resize and layouts will adjust automatically as you type. You no longer have to manually place your controls and you won’t find yourself locked into a pre-determined amount of space.

The dynamic repositioning of controls takes place within an area called the control area. The control area of a screen occupies a sub-section of the body of a screen; its size is controlled by the global theme. The control area for each banner style is defined in the theme settings using offsets.

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 want, and TrueUpdate will re-position all the controls so that everything is visible and a visually appealing look is achieved.

This is not to say that you do not have any control over how controls will be displayed on your screen; in fact, it’s just the opposite. Many screens (Edit Fields, Checkboxes, etc.) allow you to add as many as 32 controls to your screen, which TrueUpdate 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 actually use it yourself. Try playing around with the settings of a Check Boxes or Select Folder screen and observe how TrueUpdate positions your controls to achieve the best look possible.

Themes

A theme is a group of settings and images that control the way your update 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 TrueUpdate determine the general appearance of your screens and the controls they contain. Rather than managing the position of screen controls or the banner style used, themes determine the color and font of screens and controls. Themes are project-wide and affect all screens in the project 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 across your entire project.

Choosing a Theme

You can choose a theme for your project on the Theme tab of the Project Settings dialog, which can be accessed by choosing Project > Theme.

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

TrueUpdate 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 > Theme.

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 click OK to save your changes.

Make sure that your new theme is selected and click 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 TrueUpdate 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, TrueUpdate 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 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.

Other Options

There are a few other options in TrueUpdate that relate to the user interface. 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.

TrueUpdate 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 Options tab of the Project Settings dialog: Project > Options.

To choose a custom icon, enable the "Use custom icon" option, click the browse button, and locate the icon of your choice.

To hide the taskbar icon, simply select the appropriate option (i.e. "System tray" or "Hidden") in the Taskbar Visibility section of the Options tab.

Actions

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

Dialog actions are used to show pop up dialogs to the 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 a 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 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 by using a progress screen; however, there are situations where a status dialog may be more appropriate.

Tip: For more information on the Dialog and StatusDlg actions, please consult the help file.

Alternative Interfaces

Silent Updates

Although the user interface is the most important aspect of most updates, there may be occasions when a "silent" update is preferred. A silent update requests no input from the user, and performs its work invisibly.

For example, if your update will be run regularly on system startup and can function completely using hard-coded values, you may prefer your update to act entirely in the background, unseen by the user--whether to avoid annoying the user, or to prevent the user from interrupting the update process.

There are two main steps in creating a silent update. The first, and least complicated, is ensuring that the update runs in a ‘hidden’ mode. This is accomplished by selecting the Hidden option in the Taskbar Visibility section of the Options dialog (which can be accessed by choosing Project > Options). This will prevent the TrueUpdate Client from displaying an icon on the Windows taskbar while it is running.

Next, your update must be configured in such a way that it requires no input from the user. This means that everything must be anticipated and handled in your scripts. Any paths must be hard-coded in or determined automatically (e.g. registry keys, INI files, etc.) without any input from the user.

As a backup plan, you could configure your update to ask the user for any information that it cannot determine automatically. This negates the purpose of a silent update, but may be preferable to the update failing all together.

Dialog-based Updates

A dialog-based update uses popup dialogs for its user interface, essentially replacing the full screens of a wizard style interface with an interface made up of small, simple dialogs or "message boxes." This approach aims to offer a streamlined interface to the user, presenting a minimum amount of information without any of the graphical panache of TrueUpdate’s fully themed screens.

The dialog interface style is most often used by developers who wish to incorporate TrueUpdate directly into another application, and who want the update process to appear tightly integrated into their product. The dialog-style updates you can create with TrueUpdate use standard Windows message boxes that will appear just like any standard messages and dialogs that are displayed by your own application.

Tip: Another way to make the update process appear integrated with an application is to create a custom theme. Using custom themes, it is possible to make an update with a wizard-style interface that closely matches the look of a particular application.

In a dialog-based update, you do not use screens or any of the screen actions. Instead, you perform all required actions in the client script and server scripts. The client script would check for a connection to the Internet and download the server script. Then, your server script would perform all required update functions, without calling upon any screens.

Any information that needs to be presented to the user or received from the user is done using actions like Dialog.Message and Dialog.Input. If you want to display the progress of a lengthy action (like File.Copy or HTTP.Download), you can use actions such as StatusDlg.Show, StatusDlg.SetMeterPos and StatusDlg.Hide.


Chapter 6: TrueUpdate Servers

User's Guide - Chapter 6: TrueUpdate Servers

TrueUpdate Servers

One of the best features of TrueUpdate is that it uses standard server technology. It doesn’t require any proprietary hardware or software--all you need is a location where you can host the three server configuration files. These locations are called TrueUpdate Servers.

What Are TrueUpdate Servers?

In TrueUpdate, the term TrueUpdate Server refers to the location of your server configuration files. In other words, a TrueUpdate Server is any location where the TrueUpdate Client can download your server configuration files. This can be a standard HTTP server, a standard FTP server, or even a folder on your local area network.

The server configuration files allow the TrueUpdate Client to update its client-side data and executable files if newer versions are available, allow it to determine whether an update is required, and tell it the exact steps to take in order to perform the update. They are generated whenever you build a project. Once you upload the server configuration files to a location where the TrueUpdate Client can find them, that location becomes a TrueUpdate Server.

Tip: You can set up multiple, redundant TrueUpdate Servers by hosting the configuration files at more than one location.

Each TrueUpdate Client contains a list of all the locations where it can download the configuration files. The items in this list are also called TrueUpdate Servers. In this context, a TrueUpdate Server is the collection of settings that describe a location where the server configuration files can be found and the method that should be used to download them. These settings include a name that uniquely identifies the TrueUpdate Server along with the location (e.g. a URL) and any other connection details that are required to access the files, such as a username and password.

Tip: TrueUpdate can automatically upload your server configuration files to your TrueUpdate Servers via FTP, SFTP, or direct file copy. You can configure these automatic upload locations on the Upload tab of the Build Settings dialog, which you can access by choosing Publish > Settings from the program menu.

Types of TrueUpdate Servers

TrueUpdate provides a variety of methods for downloading server configuration files. All file access is handled using standard protocols--TrueUpdate doesn’t require any special hardware or specific types of servers.

Each download method is represented as a different "type" of TrueUpdate Server. The four types of TrueUpdate Servers are listed below.

HTTP Server

An HTTP TrueUpdate Server is a location (folder) on any Web server. For this type of server, the TrueUpdate Client will download the server configuration files from the Web site using the HTTP protocol. TrueUpdate uses Internet Explorer’s connection settings, so even if a client is behind a proxy server, they should have no problems provided they are able to use Internet Explorer successfully.

HTTPS Server

An HTTPS TrueUpdate Server is a location (folder) on a secure Web server. For this type of server, the TrueUpdate Client will download the server configuration files from the server using the HTTP protocol exchanged over an SSL (Secure Socket Layer)-encrypted session. This is known as the "secure hypertext transfer protocol." As with HTTP, TrueUpdate also uses Internet Explorer’s connection settings for HTTPS connections, so the same likelihood of achieving a successful connection across a proxy server exists for this method as well.

Note: This type of location requires that you have access to a secure Web server.

FTP Server

An FTP TrueUpdate Server is a location (folder) on an FTP server from which the TrueUpdate Client will download the server configuration files using FTP (file transfer protocol).

LAN/Local Server

As its name suggests, a LAN/Local server is a location (folder) either on a local drive, a mapped network drive, or a network path. In this case, the TrueUpdate Client copies the server configuration files from the TrueUpdate Server location on the network.

Note: This type of server is most useful when you are using TrueUpdate to update applications within your organization. Keep in mind that those without access to your local area network will be unable to download files from this type of TrueUpdate Server.

Adding, Removing and Editing Servers

All TrueUpdate Servers can be added and configured through the TrueUpdate Servers tab of the Project Settings dialog. You can access this dialog by choosing Project > TrueUpdate Servers from the program menu.

You can add a TrueUpdate Server by clicking the Add button and selecting the appropriate server type from the menu. Once you have selected a server type, a properties dialog will appear allowing you to specify how the server will be accessed. Each server’s properties depend upon what type of server was selected. With that in mind, properties generally include a unique name or identifier that is used to refer to the TrueUpdate Server, the folder path or address, and any other connection settings that are necessary to access it.

Once a TrueUpdate Server’s settings have been configured through its properties dialog, clicking OK adds it to the list on the TrueUpdate Servers tab. If the server’s settings need to be adjusted later, you can highlight the desired TrueUpdate Server and click the Edit button to open its properties dialog. Also, note that any TrueUpdate Server can be easily removed. Simply highlight the desired TrueUpdate Server and click the Remove button.

Note: TrueUpdate supports as many TrueUpdate Servers as you require.

TrueUpdate Server Redundancy

Although most updates can be served from a single location, many developers find it useful to have one or more backup servers in case of problems with the primary server. TrueUpdate makes this easy to accomplish by allowing you to set up multiple TrueUpdate Server locations.

TrueUpdate’s approach to handling redundancy is straightforward: simply add more TrueUpdate Server locations to the list, and see that the server configuration files are uploaded to those locations. If a server is unavailable for any reason, the TrueUpdate Client will move on to the next one until it can establish a connection and download the configuration files.

In fact, TrueUpdate is designed to support redundancy to any level. You can add as many TrueUpdate Server locations as you need, and you can mix the server types as well--for example, you could have a primary HTTPS server, followed by a pair of HTTP servers and an FTP server as backups.

Tip: If you’re designing an update for a mission critical application, use TrueUpdate’s support for redundancy to ensure that, given appropriate access to the Internet or your internal network, your TrueUpdate Client can always access a TrueUpdate Server.

By default, any project generated through the project wizard is designed to run through the list of TrueUpdate Servers defined in the project until the server configuration files have been downloaded successfully. In other words, if the first server fails, it will automatically try the next location. The default project achieves this functionality by using a TrueUpdate.GetUpdateServerList action to get a list of all of the servers, and then using a TrueUpdate.GetServerFile action to download the server configuration files from each TrueUpdate Server in turn.

While simply going through the list of TrueUpdate Servers in the order they are defined on the Project Settings dialog is the default behavior, this is by no means the only option available to you. Since the default server interaction is scripted, it is possible for you to modify it even further. For example, you may want to use different TrueUpdate Servers in specific cases. You could change the primary server for clients distributed in different geographic locations, for instance--letting the client automatically choose the appropriate TrueUpdate Server location whether it's run from North America, Europe, or Asia. By customizing the script, you can have full control over the entire process. This allows you to choose the best server for each particular client.

TrueUpdate Server Scalability

From the ground up, TrueUpdate was created to be fully scalable and fault-tolerant. In addition to being able to easily configure the client application to access redundant servers, you control the underlying server technology. Because TrueUpdate uses standard Internet protocols such as HTTP, HTTPS, FTP and LAN, you are free to take advantage of the full range of server technologies available to you. Unlike other update services that use proprietary server hardware and software, TrueUpdate allows you ultimate control over load-balancing and distributed processing of client/server requests.

Another exciting feature of TrueUpdate is the client’s ability to update itself with the newest client executable or data file. That way, if any changes are made to the client--such as an updated list of TrueUpdate Servers--these changes can be propagated through to the existing clients that have already been distributed. While we generally recommend not modifying the client after it has been distributed, this feature can be a lifesaver if you run into a situation where you require additional servers or need to change existing ones.

Note: In order for the client to update itself, it must be able to access at least one of its previously defined TrueUpdate Servers. In other words, you cannot simply update the TrueUpdate Server list on your end, switch servers entirely, and expect the client to update itself. Before the client makes use of any new servers, it must know what those new servers are.


Chapter 7: Session Variables

User's Guide - Chapter 7: Session Variables

Session Variables

When designing an update, it is 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 TrueUpdate.

What Are Session Variables?

Session variables are designed to handle dynamic data during the update 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 TrueUpdate: built-in session variables, and custom session variables.

Built-in Session Variables

For convenience, TrueUpdate 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 TrueUpdate Client 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:

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

%Copyright%

The copyright message for your product. The value of this variable is set on the Session Variables tab of the Project Settings dialog.

%DAOPath%

The path to the user’s DAO (Data Access Objects) directory.

%DesktopFolder%

The path to the user’s Desktop folder. On Windows NT/2000/X/VistaP, 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 updating. 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 TrueUpdate Client executable was run from (e.g. "C:" or "D:").

%SourceFolder%

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

%SourceFilename%

The full path, including the filename, for the current update executable. For example, if the user was running "update.exe" from "C:\Downloads," %SourceFilename% would be expanded to "C:\Downloads\update.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.

%WindowsFolder%

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

Custom Session Variables

You can define your own session variables to supplement the built-in session variables that are automatically provided in TrueUpdate. 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 the client 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.

You can access the Session Variables tab by choosing Project > Session Variables from the program menu.

All session variables defined on the Session Variables tab are stored in the client data file. This means that any changes to the list of session variables will in turn change the client data file. TrueUpdate handles changes to the client data file automatically--in fact, a copy of the latest client data file is stored at each TrueUpdate Server location so the TrueUpdate Client applications can make sure they are always using the latest version. In order for a TrueUpdate Client to update its data file, however, it needs to restart itself. If you foresee needing to change the values of these session variables often, you should consider whether they could be defined in your Server Script using actions instead. Since changes to the Server Script aren’t stored in the client data file, they don’t cause the TrueUpdate Client application to restart.

Tip: Generally, session variables that aren’t displayed on the client screens should be created from your Server Script so they can be changed without affecting the client data file.

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

The Product Information category contains three 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, TrueUpdate 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 in the Custom category can be removed from your project. To remove a custom session variable, click on the desired session variable name in the list to highlight it, and then click on the Remove button. The session variable will be removed from the list.

Using Actions

Session variables can also be removed at any point during your update with an action. The action used to remove a session variable is called SessionVar.Remove and can be found in the "SessionVar" action category. The function prototype for this action can be seen below:

SessionVar.Remove(string VariableName)

For example, if you want to remove a session variable called %MyVar%, the action script would look like the following:

SessionVar.Remove("%MyVar%");

Note: Since both custom and built-in session variables behave the same, it is possible to remove a built-in session variable using the SessionVar.Remove action. For this reason, extra care should be taken when removing session variables with actions.

Using Session Variables on Screens

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 update, and therefore could not be directly entered at design time.

Tip: Session variables can also be useful in multilingual updates 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

TrueUpdate also contains an action that will prevent the recursive expansion of session variables. This action is called SessionVar.Get and can also be found in the "SessionVar" actions category. The function prototype 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 TrueUpdate’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 to not only offer software in a variety of languages, but also to keep this software current.

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

Internationalizing Your Project

TrueUpdate has the ability to automatically detect the user’s system’s language and to display messages and screens in that language. The developer has full control over which languages are supported in their project and over the content presented to the user.

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

TrueUpdate allows you to localize your 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 TrueUpdate Client detects is based on the user’s regional and language settings. These settings allow Windows users to configure which language is displayed, which input locale is used and which keyboard layout is supported in the Windows operating system environment. These settings are usually configured when Windows is installed and can usually be changed from the Windows Control Panel. For example, in Windows XP, a user can select Start > Settings > Control Panel and start the Regional and Language Settings control panel application.

Each language in Windows has a constant language identifier. A language identifier is a standard international numeric abbreviation for the language 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 TrueUpdate help file.) TrueUpdate maps all known languages and sub-languages according to the language identifiers used by Windows.

Tip: TrueUpdate maps language identifiers to language names in a file called language_map.xml located in TrueUpdate’s Language folder (usually "C:\Program Files\TrueUpdate 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 client 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 update. 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 client 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 update will not run on that system; rather, it means that the update 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 client 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 update with English as the default language. If your user runs the update 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 TrueUpdate Client. Language files do not contain project-specific messages, such as the text that you enter on screens.

The language files are located in TrueUpdate’s Languages folder (usually "C:\Program Files\TrueUpdate 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 TrueUpdate, 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 to create a French language file:

1. Open Windows Explorer to TrueUpdate’s Languages folder (usually "C:\Program Files\TrueUpdate 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 TrueUpdate 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 TrueUpdate. The new language will now be available.

9. Feel free to visit the Indigo Rose user forums (www.indigorose.com/forums/) and share the file with others so they can use your translations in their projects.

Adding Languages

To add a new language to your project, 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:

• TrueUpdate 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 screen 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 specific screen’s properties. Next, select the language that you want to enter text for in the language selector. Then, simply type the text that you want for the various fields in 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 TrueUpdate, 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 TrueUpdate or that you need to work with the project in other ways while the translation is taking place. TrueUpdate has a solution for this situation. You can:

1. Select the screen that you want to have translated in either the client or server screens list.

2. Click the Advanced button (this will open a popup menu).

3. Select Export Language and then the language that you want to export to.

4. Choose a location to save the file to.

5. Send the exported file to your translator.

6. When you receive the file back, select the screen in the Screens list.

7. Click the Advanced button and then choose Import Language from the popup menu.

8. Locate the translated file and select Open.

9. 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 the default messages, your modified language file may be overwritten by a future update to TrueUpdate. To avoid this, you may want to rename any language files that you modify, for example renaming english.xml to my_english.xml. (In cases where there is more than one language file for a given language, TrueUpdate 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 update 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.GetUpdateLanguage. 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 for the language 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 TrueUpdate 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 use 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.GetUpdateLanguage

Application.GetUpdateLanguage is used to retrieve the primary and secondary language ID that is actually being used by the TrueUpdate Client. Note that Application.GetUpdateLanguage may return a different result than System.GetDefaultLangID if the language being used by the client 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 update on their system. Even though their system uses primary ID 10 and secondary ID 13 (which would be returned by System.GetDefaultLangID and corresponds to a dialect of Spanish), Application.GetUpdateLanguage would return a primary ID of 9 and a secondary ID of 1, which is the update’s default language (English). The TrueUpdate Client would be using the default language because Spanish was not added to the project at design time.

The value returned by Application.GetUpdateLanguage 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 project.

Changing the Current Language

Normally, if TrueUpdate 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.SetUpdateLanguage action.

The Application.SetUpdateLanguage action allows you to directly set the primary and secondary language IDs that will be used for the update. Calling this action changes all subsequent error and status messages as well as the text shown on the screens. It effectively "forces" the TrueUpdate Client 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 client is run on anything other than Simplified Chinese.

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

In other words, you want to override the default language rule and force your client
to use Simplified Chinese whenever Traditional Chinese is detected. You can do so easily by placing the following short script at the beginning of your client script, before any screens or 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.SetUpdateLanguage(4, 2);
end

Testing Different Languages

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

Application.SetUpdateLanguage(16, 1);

You could even modify your client script to check for a custom command line option, so you could force your TrueUpdate Client 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 client has been distributed.

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

Localizing Actions

You may have noticed that there is no language selector when editing scripts in TrueUpdate. 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 client is using, and then displays one of two possible greetings:

local tblSysLang = Application.GetUpdateLanguage();

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

if (tblSysLang.Primary == 12) then
Dialog.Message("Bienvenue",
"Bienvenue à la mise à jour");
end

The Application.GetUpdateLanguage action returns a table containing the primary and secondary language ID that is being used by the TrueUpdate Client. 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 TrueUpdate Client 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 update; 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.GetUpdateLanguage 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

TrueUpdate allows you to get and set translated messages from the language files and screens at run time. This is done through several actions.

TrueUpdate.GetLocalizedString

This action allows you to retrieve the localized text for a general message from the language files at run time. The message will be returned in the current update language. For example, the default language files provide messages to confirm if the user wants to abort the update. Here is a way to show a dialog that confirms if the user wants to abort the update in the current language:

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

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

Note: The message IDs (like MSG_CONFIRM) for the localized message strings can be found in the XML language files, e.g. English.xml in the TrueUpdate Languages folder.

TrueUpdate.SetLocalizedString

This action allows you to change the value of a localized string. This could be useful if you want to override the default value of an error message so that 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 update. By default it is "The update 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?"

TrueUpdate.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 update 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 TrueUpdate.GetLocalizedString and TrueUpdate.SetLocalizedString do, except that they will only access strings used on the current screen.


Chapter 9: Security

User's Guide - Chapter 9: Security

Security

Any time data is exchanged over the Internet security is an issue. TrueUpdate normally relies on Internet communication to update software; therefore, it is also subject to Internet security issues.

This chapter will explain the security measures that have been implemented in TrueUpdate and outline ways in which you can further enhance your update application’s security.

Security in TrueUpdate

The security of your product is only as strong as its weakest link. For that reason, measures have been taken in the design and development of TrueUpdate to provide as much security as is practical for the product.

Since TrueUpdate was designed to be flexible enough to accommodate your specific updating needs, there are security measures that can only be implemented by you, the developer. In this chapter, we will examine TrueUpdate’s built-in security features and the additional measures you can take to further secure your software updates.

Client Side Security

TrueUpdate takes steps to ensure that the update files you distribute with your software are secure. The details of your update application, such as scripts and project settings, are hidden from casual inspection.

In general, you will distribute two files with your update application: the client executable file and the client data file. Below is a short overview examining how these files and the file updating process are protected.

Client Executable File

The client executable file does not contain any information specific to your update application. It is a runtime executable that is used by all TrueUpdate users. For this reason there is no special protection applied to it.

Client Data File

The client data file contains your client script, screens and most of the project settings you configured at design time. Since some of this information can be sensitive, the file is compressed and encrypted to prevent unauthorized inspection or tampering.

At run time the scripts, screens and settings in the client data file are read directly into memory, without being written to the hard drive (even temporarily) in any unencrypted form. The only files that are temporarily created by the TrueUpdate Client are not sensitive in nature, and are deleted as soon as the update application shuts down.

Client File Updating

Every time you publish your update, the MD5 hash of the current client data file is stored in the server data. This allows the client application to automatically determine whether its data file is up to date. If the MD5 hash of the client data file on the user’s system does not match the one that the server file was published with, the client data file will automatically be downloaded and updated. So, if your client data file is tampered with on the client system (e.g. if it is infected with a virus, or damaged by the user), it will be removed and updated the next time an update is requested.

How MD5 Security Works

An MD5 hash is a digital signature that can be used to uniquely identify any piece of data. It is the result of a special calculation that can be applied to any kind of data. This calculation process is strictly one-way. Although you can calculate the MD5 hash for any value, you cannot later retrieve the value from the MD5 hash. It is currently impossible to reverse the process.

So, if you calculate the MD5 hash of a file, that MD5 hash will always be the same for that exact file. If even one bit of data in the file is modified, the MD5 hash will be different. This method is a great way to ensure data integrity.

Note that you can calculate and validate MD5 hashes on your own files using the Crypto plugin available for TrueUpdate.

Server Files Security

Your TrueUpdate server files are especially vulnerable because they are usually publicly available on your TrueUpdate servers. For this reason, there are strong security measures in place to protect them.

Types of Server Files

When you publish your update to a TrueUpdate Server, several files are uploaded. The files all use your custom server file prefix for file names and have the file extensions .ts1, .ts2 and .ts3.

Server Data File

The server data file has the extension .ts1 on the TrueUpdate Server. This file contains all of your server scripts and screens. This file is the most critical security concern as it contains information about how you update your software and may also contain sensitive passwords and file locations.

The server data file is encrypted using private-key Blowfish encryption. The private key is the unique, product-specific key that you specify in TrueUpdate at design time (see Project > Options from the menu.) This private key is stored in the client data file, which is also encrypted using a different encryption scheme.

What is Blowfish Encryption?

Here is a definition from the official Blowfish Web site (www.schneier.com):

"Blowfish is a symmetric block cipher that can be used as a drop-in replacement for DES or IDEA. It takes a variable-length key, from 32 bits to 448 bits, making it ideal for both domestic and exportable use. Blowfish was designed in 1993 by Bruce Schneier as a fast, free alternative to existing encryption algorithms. Since then it has been analyzed considerably, and it is slowly gaining acceptance as a strong encryption algorithm. Blowfish is unpatented and license-free, and is available free for all uses."

Only update clients that were built with the same encryption key that was used to encrypt the server data at build time can read the server file. For this reason, it is very important not to lose the encryption key used for an update project. It is also important not to change the encryption key after your update application has been distributed to end users.

Tip: The longer your encryption key, the harder it is to break. It is recommended that your encryption key be at least 20 characters long.

Updated Client Data File

The updated client data file has the extension .ts2 on the TrueUpdate Server. It contains the latest version of your client data file, and is placed on the TrueUpdate Server in case the user does not have the most recent version of the client data on their system at run time. If the TrueUpdate Client sees that the .ts2 file is newer than its existing client data file, it will download the .ts2 file and replace the client data file with the newer version.

Since the client data file is already encrypted, the updated client data file doesn’t require any additional security measures.

Updated Client Executable File

The updated client executable file has the extension .ts3 on the TrueUpdate Server. It is a compressed version of the client executable. Like the updated client data file, the updated client executable is used to update the user’s TrueUpdate Client application when the user does not have the most recent version of the client on their system.

Since this file does not contain any of your product-specific information, no special protection has been applied to it.

Client-Server Communication

As you probably know by now, the TrueUpdate Client application normally needs to communicate with a TrueUpdate Server in order to update your software. The question is, what kind of communication takes place?

There is no "default" communication between your TrueUpdate Client and your TrueUpdate Servers. If you build a TrueUpdate project that has an empty client and server script, no client-server communication takes place. All client-server communication is specified through script, whether it is created manually or with the project wizard.

The most common way that your projects will interact with your TrueUpdate Servers is through the action TrueUpdate.GetServerFile. This action downloads the server file you have specified from a TrueUpdate Server and then runs the server script. All of this communication takes place through the protocol specified for the TrueUpdate Server (HTTP, HTTPS, FTP, or LAN).

The TrueUpdate Client never sends information about the client or client system to the TrueUpdate Server. It merely downloads the specified server file, decrypts it and then runs the script. It may also do a self-update if necessary.

Of course, TrueUpdate provides a wide variety of actions that you can execute to perform all sorts of client-server communication over several protocols. The following sections will look more closely at some of these available options.

Secure Protocols

TrueUpdate provides you with several secure protocols that can be used in both the design and run-time phases of development.

SFTP

TrueUpdate allows you to use the SFTP (Secure File Transfer Protocol) to upload server files at publish time. SFTP is a transfer method that uses SSH to transfer files using AES, DES, and Blowfish encryption. Unlike standard FTP, it encrypts both commands and data, preventing passwords and sensitive information from being transmitted in the clear over the network. It is functionally similar to FTP, but because it uses a different protocol, you cannot use a standard FTP client to talk to an SFTP server, nor can you connect to an FTP server with a client that supports only SFTP. TrueUpdate’s implementation of SFTP uses SSH2.

HTTPS

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.

The TrueUpdate Client can transfer files and data from a Web site using the actions HTTP.DownloadSecure and HTTP.SubmitSecure. These actions will ensure that the connection between your client and your server is secure. Note that your Web server must be specially configured in order to support HTTPS.

Custom Client-Server Communication

There may be times when you want your update client to communicate with a Web server in a way that is not built into TrueUpdate. Some examples are:

· validating the user’s serial number against a Web database before providing updates

· tracking which customers have updated the software and when they last updated in a Web-based database

· allowing the user to renew a software subscription through your update client. The client will gather payment data and then submit it to your Web server through the HTTPS protocol for payment processing

· submitting user feedback from the TrueUpdate client to a Web script that in turn emails the information to you

Fortunately, TrueUpdate comes with built-in actions to facilitate this kind of communication, namely HTTP.Submit and HTTP.SubmitSecure. These two actions allow you to send data to a script on your Web server and then receive a response from the server. These actions should work with any type of standard Web server, such as Apache or Microsoft IIS, and with any type of scripting language that allows CGI communication, such as ASP, PHP, Perl, etc.

By providing a method to interface with Web scripts, TrueUpdate gives you the flexibility to add further security features to the client-server communication process beyond the built-in actions it comes with. This ability to utilize any Web scripts you develop greatly adds to the extensibility of TrueUpdate.

Important Considerations

When planning product security, it is important to keep the following in mind: even the best security measures can be circumvented. This is clearly illustrated by successful breaches of highly sophisticated security systems such as DVD encryption and secure government communications.

In addition to securing your installer, update application, and perhaps your installed application, you may want to consider controlling the distribution of your installation files. After all, a software thief can’t steal something he or she can’t find.

One final point to keep in mind is that too much security can be a bad thing. While it is important to secure your application to prevent against unauthorized use, it is equally important to allow legitimate users a painless update process.


Chapter 10: Building and Distributing

User's Guide - Chapter 10: Building and Distributing

Building and Distributing

Once you have designed your update system, you need to build and distribute it. Fortunately, TrueUpdate makes this as seamless as the actual design process.

From automatically uploading to your chosen TrueUpdate Server locations, to a handy list describing what you need to do after the build, TrueUpdate makes building your project fast and easy.

The Build Process

Once you have finished creating your TrueUpdate project, you must use it to generate the actual TrueUpdate Client application and server configuration files. This is similar to a programmer compiling source code into a working executable.

When building your update, TrueUpdate will go through the following steps in the order listed below:

1. Run any pre-build programs that have been specified.

2. Collect all of the fonts needed for the screens in your update.

3. Convert all of the images used by the screens.

4. Collect all of the required language files.

5. Collect all includes (external script files) that have been specified.

6. Collect all action plugins that have been specified.

7. Collect any external files that have been specified (e.g. a custom icon).

8. Copy the run-time engine into the specified output directory.

9. Create the client data file by compressing all of the collected files and saving all necessary client information.

10. Create the server configuration files (*.ts1, *.ts2, and *.ts3).

11. Upload the server configuration files and the server information file (*.tsx) to any automatic upload locations you’ve defined in the project.

12. Run any post-build programs that have been specified.

Note: When TrueUpdate uploads the files to your automatic upload locations, it only uploads the files that it needs to (the ones that have changed since the last time your project was built). For instance, the .ts2 file will only be uploaded if it differs from the .ts2 file that is already on the server, and the .ts3 file will only be uploaded if its file version is newer than the file version of the .ts3 file on the server.

The Publish Wizard

With the goal of making the build process as seamless as possible, TrueUpdate includes a publish wizard to assist you. The publish wizard can be accessed by choosing Build from the Publish menu.

The first step in the publish wizard allows you to specify three important items: the output folder, the name of the TrueUpdate Client executable, and the server files prefix.

The output folder is simply the location where your TrueUpdate Client and server configuration files will be generated on your local system.

The TrueUpdate Client filename determines the name of the client executable that you will distribute to your users.

The server files prefix is the name that will be used for the server configuration files, i.e. the name that will be used for the .ts1, .ts2, and .ts3 files.

Note: The first time you build your project, you will be able to edit the server files prefix directly. However, on all subsequent builds the server files prefix field will be disabled; to edit the server files prefix, you will need to click the Change button. Clicking the Change button displays a warning before allowing you to change the value, because changing the server files prefix will "break" an existing distribution. The TrueUpdate Client needs to know what the server files prefix is in order to download the server files. If you change the server files prefix, you will need to redistribute the TrueUpdate Client application to all of your users.

The second step in the publish wizard prompts you to configure your upload locations. You can use this feature to automatically upload the server configuration files to your TrueUpdate Server locations. You can also use it to upload the files to other locations, such as a backup file server or a folder on your network for testing.

Note that you can add and edit upload locations in this step, and you can enable or disable the individual upload locations by checking or unchecking the corresponding checkbox.

Once you’ve selected the locations that you want to upload the server files to, you can click the Build button to start the build process.

Once the build process is complete, the publish wizard will display a summary of the build process and any errors or warnings that occurred during the build.

There are two options below the summary that control what happens after you click Finish. One determines whether TrueUpdate will automatically open the output folder for you (for example, if you wanted to immediately test the update, you won’t have to navigate to the output folder yourself). The other controls whether to display a publish report listing the files that have been output by the build process and what you need to do next.

When you’re finished reading the summary, you can click Finish to exit the publish wizard.

Build Settings

The Build Settings dialog allows you to specify default settings for the publish wizard and to configure additional features that affect the build process or the generated files. You can access the Build Settings dialog by choosing Publish > Settings from the program menu.

Output

The Output tab is where you can set the output folder, the TrueUpdate Client filename, and the server files prefix.

The output folder is where all of your update files will be built to. This can be any location on a local hard drive or on the local network. All of the files that TrueUpdate uses are built to this location, including both client files and server configuration files.

There are two client files that get built: an executable file (the "client executable") and a data file (the "client data file"). The name that you enter in the TrueUpdate Client filename field is the full name that will be used for the executable file.

TrueUpdate automatically chooses a name for the client data file based on the executable file’s name. For example, if you were to specify "Update.exe" in the TrueUpdate Client filename field, the data file would be named "Update.dat." If you were to specify "myupdate.exe," the data file would be named "myupdate.dat."

Upload

A great new feature in TrueUpdate is the ability to have your server configuration files automatically uploaded for you. This can save you a lot of time when distributing your updates, especially if you have more than one server to upload to.

You can configure as many or as few upload locations as you want, but in general each upload location will correspond to a TrueUpdate Server used in your project.

Note: When specifying upload locations it is not necessary to specify any file names. You only need to specify the folder where the files will be uploaded to.

Upload locations come in three different varieties that correspond to the upload methods used: FTP, SFTP, and File Copy.

FTP

Uses the File Transfer Protocol to upload your server files to a specific folder on an FTP server.

SFTP

Uses the Secure File Transfer Protocol to upload your server files to an FTP server. The SFTP upload method is very similar to the FTP upload method except that it encrypts the transfer of data between the client and server.

File Copy

Copies the server files to a writable folder on a local storage device (e.g. hard drive, floppy drive, USB key) or a LAN location (i.e. a folder on the local area network). Normally used with LAN/Local TrueUpdate Servers or internal Web/FTP servers.

Constants

Constants are essentially design time variables. They are similar to session variables, but instead of being expanded as the user runs the update, they are expanded when you build the project. In other words, when you build your project, all of the constants are automatically replaced by the values assigned to them.

You can define constants on the Constants tab of the Build Settings dialog, which you can access by choosing Publish > Settings.

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

Each constant has a name that will be replaced by this value throughout the project when the project is built. It’s exactly like a big search-and-replace operation that happens whenever you build the project.

Since each constant is essentially just a name that gets replaced with different text, you can use them just about anywhere. You can use them on screens, in file paths, in actions…pretty much anywhere that you can enter text.

Note: Design-time constant names can be in any format you like. One recognizable format which we recommend is to write the constant name in all capitals, using underscores in place of spaces between words, like so: LATEST_FILE_VERSION.

Unattended Builds

An unattended build is when a project (in this case a TrueUpdate project) is built with little or no developer interaction, often by another software process. Unattended builds are usually used when many different tasks need to be accomplished in sequence with the TrueUpdate build process. In these cases a software application or a simple batch file is used to automate the tasks. An example would be using a program to compile the source code for an application, building that application’s installer using Setup Factory, and then building the update using TrueUpdate.

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 the server file prefix. The possibilities are endless.

For example, you could create a batch file that would generate a unique update for every one of your customers, with the customer’s name showing up on one or all of the screens during the update.

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

Pre/Post Build Steps

There may be instances where you want to run a program either before or after your project has been built. TrueUpdate makes this process easy. On the Pre/Post Build tab of the Build Settings dialog, you can set a program to Run Before Build, and a program to Run After Build.

The uses of this feature are limited only by your imagination. You could, for example, chain several builds together by having one project call another through the Run After Build option. Or you could run an "automated backup" batch file that compresses all of the server files into a single zip file, and then copies the zip file to a folder on your network. 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 the design environment to pause while the other program is open, check the Wait for program to finish running checkbox.

Build Preferences

TrueUpdate includes a number of preferences that affect how TrueUpdate handles the build process. You can find these preferences by choosing Preferences from the Edit menu and selecting the Build category.

The build preferences allow you to control whether TrueUpdate opens the output folder, whether it shows the publish report by default, whether it displays the publish wizard before building, and (when not using the wizard) whether a confirmation dialog is displayed before the build process begins.

You can also specify a list of fonts to exclude from the build process. Fonts take up additional space in your update so it is often a good idea to exclude any fonts that you know your end user will already have. By default this field includes Arial, Courier New, and Times New Roman.

Integrating the Client into your Software

Once you’ve built the TrueUpdate Client, you need to integrate it into your software. Integrating the client simply means including it with your software distribution and providing one or more ways for your users (or your software) to initiate an update.

Note: The TrueUpdate Client can be thought of as the client executable and the client data file.

Integrating TrueUpdate can be as simple as putting a shortcut on the Start menu that will launch the client executable, or it can be as sophisticated as having your main application run the client executable every 15 days. You could provide an item in your application’s menu to initiate an update, or even a button on your application’s toolbar. The level of integration is up to you.

Note: The TrueUpdate Client program is an executable that can be run normally from Windows.

Integrating TrueUpdate into your application involves two basic steps: adding the client files to your software distribution, and providing one or more ways to initiate an update.

Step 1: Adding the Client Files

The TrueUpdate client consists of two files: a client executable, and a single data file. By default the client executable is named TrueUpdateClient.exe and the data file is named TrueUpdateClient.dat. Both files are generated when you build your update.

Note: A complete list of files that you need to distribute can be found in the publish report that is generated each time your build your update.

Exactly how you add the client files to your distribution depends on the distribution method you use. It can be as simple as including the two files in a zip archive, or as sophisticated as using a professional installation tool like Setup Factory.

You can install the files anywhere on the user’s system, but it’s usually best to install them in the same place as your application. This way the location of your software can easily be determined at run time by using the built-in variable _SourceFolder, or the built-in session variable %SourceFolder%.

If you’d prefer to have the client files in a different folder, remember to provide some way for the TrueUpdate client to determine the path where your software was installed. For example, you could write the path to a Registry key or INI file with your installer and then use actions to read that information into a variable.

Step 2: Triggering TrueUpdate

Initiating an update is simply a matter of running the TrueUpdate client. In fact, your users could check for an update simply by double-clicking on the client executable.

Of course, there are several more sophisticated ways to initiate an update. Here are some of the different ways TrueUpdate could be started:

Using a Start Menu item

Install a shortcut to the TrueUpdate client in the user’s Start menu.

Using an icon on the Desktop

Give your users the option to install a shortcut on their Desktop so they can initiate an update at any time. You could use the standard TrueUpdate client icon for this purpose, or perhaps the same icon you use for your application.

Using a menu item in your program

Provide an item in a program menu like Help > Check for Updates that will launch the client executable.

Using a toolbar button in your program

Provide a "Check for Updates" button on one of your program’s toolbars.

Automatically on starting Windows

Install a shortcut in the user’s Startup folder to automatically run the TrueUpdate Client every time the user’s system is started. You could also create a small "launcher" program that checks the number of times the system has been booted since the last update was performed and only launch TrueUpdate periodically. You could even set up an event with the Windows scheduling service if it’s active on the user’s system.

Automatically when your program starts

Launch TrueUpdate silently from your program when it’s started. You could check the system date and only launch the client if your application was last started more than a certain number of days ago. Or keep a counter of "application starts" in the Registry, and only check for an update after a certain amount of times that the user launches your program. You can even let your user specify how often they want the checks to be performed.

As a stand-alone executable, the TrueUpdate client gives you plenty of freedom to initiate the update process in a way that fits the style of your application. Which method (or methods) you choose to provide is entirely up to you.

Source Code

Here are some source code samples using ShellExecute to call the TrueUpdate Client from Visual Basic, C/C++, and C#.

Calling ShellExecute from Visual Basic

Private Declare Function ShellExecute Lib "shell32.dll" _
Alias "ShellExecuteA" (ByVal hwnd As Long, _
ByVal lpOperation As String, ByVal lpFile As String, _
ByVal lpParameters As String, ByVal lpDirectory As String, _
ByVal nShowCmd As Long) As Long

Private Const SW_NORMAL = 1

Private Sub RunTrueUpdateClient()

' Execute the program
Dim lReturn As Long

lReturn = ShellExecute(Me.hwnd, "open", _
"C:\\Program Files\\Widget Designer\\TrueUpdateClient.exe", _
"", 0, SW_NORMAL)

If lReturn <= 32 Then
MsgBox "Error executing client"
End If

End Sub

Calling ShellExecute from C/C++

BOOL RunTrueUpdateClient()
{

HWND hWindow;
int nResult;

hWindow = GetSafeHwnd();
nResult = ShellExecute(hWindow, "open"
,"C:\\Program Files\\Widget Designer\\TrueUpdateClient.exe"
,"", NULL, SW_NORMAL);

if(nResult > 32) // values above 32 indicate success
{
return TRUE; // update executed
}
else
{
return FALSE; // update not executed
}

}

Using Process components and the .Net framework from C#

using System;
using System.Diagnostics;
using System.ComponentModel;

public bool RunTrueUpdateClient()
{

   bool bReturn = true;
try
{
Process UpdateProcess = new Process();
UpdateProcess.StartInfo.FileName =
"C:\\Program Files\\Widget
 Designer\\update.exe";
UpdateProcess.StartInfo.WindowStyle =
ProcessWindowStyle.Normal;
//The Start method returns true on success
 and
//false on failure
bReturn = UpdateProcess.Start();
}
catch (Win32Exception e)
{
//An error has occurred
bReturn = false;
}

return bReturn;
}

Testing Your Update

One of the most important and often overlooked steps when creating an update is testing it after it has been built. You should test your update on as many computers and operating systems as possible. Try it on every operating system that your product supports. Windows 95, Windows 98, Windows 2000, Windows ME, Windows NT, Windows XP, Windows Vista and later all have both slight and major differences between them and should be thoroughly tested. It is also important to test the way that your update responds to different OS configurations, different service packs, monitor resolutions, color depth, and font sizes. If your update needs a lot of hard drive space, be sure to test it on systems with a very limited amount of hard drive space.

If you have made use of TrueUpdate’s multilingual support, be sure to test out each language in your update. If you are using multiple TrueUpdate servers, be sure to test each update server individually to ensure that they are all working properly.

It is very important to test before you distribute. An ‘internal build’ of your update is much easier to recall than is a public release should a problem arise.

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

Log Files

TrueUpdate’s built-in logging function can quickly become a developer’s best friend. It is enabled by default, and contains all the information that you as a developer will need to diagnose an update gone bad. Everything that happens during the update is logged, from which screens were displayed to what version of the update engine is being used.

Beyond its basic components, the update log file is fully customizable; as the developer, you can choose what information is logged and what information is not. If you require even more detail than what the built-in logging capabilities provide, you can add custom lines to the log at any point during your update.

Using log files is invaluable to developers for diagnosing problems. Let’s face it, no matter how much testing is done, there will always be one end user who hits a snag. Utilizing log files, you can find out exactly where that snag occurred, and fix the problem. As a result, you save on support costs and keep your customer happy.

Ultimately, the choice of whether or not to use the log file, and how much information should be in that log file, is up to you.

Here is an example of what a log file might look like:

[12/28/2004 16:38:11] Success Update started: C:\output\tu\TrueUpdateClient.exe
[12/28/2004 16:38:11] Notice Update engine version: 1.0.0.0
[12/28/2004 16:38:11] Notice Product: Your Product, version %ProductVer%
[12/28/2004 16:38:11] Success Language set: Primary = 9, Secondary = 1
[12/28/2004 16:38:11] Success Include script: _TU20_Global_Functions.lua
[12/28/2004 16:38:11] Success Language set: Primary = 9, Secondary = 1
[12/28/2004 16:38:12] Success Run client data event: Client Script


Scripting Guide

Contents

Welcome to the online version of the TrueUpdate 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 TrueUpdate

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

TrueUpdate Web Site

Indigo Rose Technical Support

The Lua Web Site


Introduction

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

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

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

A Quick Example of Scripting in TrueUpdate

Here is a short tutorial showing you how to enter a script into TrueUpdate and preview the results:

1. Start a new project.

2. In your project's Client Script, type in the following text:
Dialog.Message("Title", "Hello World");

It should look like this when you’re done:

3. Choose Publish > Build from the program menu and go through the publish wizard.

4. Once your project has finished building, run the created file (typically TrueUpdateClient.exe).

When the client script is run, the script you entered will be performed. You should see the following dialog appear:

Congratulations! You have just made your first script. Though this is a simple example, it shows you just how easy it is to make something happen in your TrueUpdate application. You can use the above method to try out any script you want in TrueUpdate. .


Important Scripting Concepts

There are a few important things that you should know about the TrueUpdate 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;” on a particular screen 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 TrueUpdate is concerned.

The same principle applies to function names as well. For example:

Dialog.Message("Hi", "Hello World");

...refers to a built-in TrueUpdate 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 TrueUpdate. 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 TrueUpdate 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 a screen’s On Preload event, and then enter:

Dialog.Message("The value is:", foo);

...into a different screen’s On Preload event, the second script will use the value that was assigned to “foo” on the first event. As a result, when the second screen is encountered, 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 first screen's On Preload event is triggered before the second screen's On Preload event, so the value 10 is already assigned to foo when the second screen's event 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

TrueUpdate’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 TrueUpdate 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 TrueUpdate: 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”). TrueUpdate 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 TrueUpdate 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 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. 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 TrueUpdate 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 update, 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 application in any other script.

This brings up an important point about scripting in TrueUpdate. When making a function, the function does not get “into” the engine until the script is executed. That means that if you define HelloWorld() on a screen’s On Help event, but that event never gets triggered (because the user doesn’t click on the Help button), the HelloWorld() function will never exist. That is, you will not be able to call it from anywhere else.

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 TrueUpdate 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 TrueUpdate , 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 strSearchIn inside strSearchFor
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 if run from the Client Script:

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");

Assume that the file was distributed with our update.

Now, wherever we add the following line of script to an event:

dofile(SessionVar.Expand("%TempFolder%\\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 temp folder path from the session variable %TempFolder%. 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 a script file into the scripting engine and runs it. 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("%TempFolder%\\MyScript.lua"));
require(SessionVar.Expand("%TempFolder%\\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

TrueUpdate 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 TrueUpdate as smartly and effectively as possible!

This section will explain TrueUpdate’s error handling methods as well as cover a number of debugging techniques.

Error Handling

All of the built-in TrueUpdate 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 TrueUpdate’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 TrueUpdate 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 TrueUpdate when you build 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 TrueUpdate’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

TrueUpdate 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 application. 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 TrueUpdate runtime has the ability to show a debug window that can be used to display debug messages. This window exists throughout the execution of the application, 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 application, 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

TrueUpdate 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 application, 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 the On Preload event of an Edit Fields screen:

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

Help File

The TrueUpdate help file is packed with good reference material for all of the actions and events supported by TrueUpdate , and for the design environment itself. You can access the help file at any time by choosing Help > TrueUpdate 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 TrueUpdate. 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 > TrueUpdate User’s Guide from the menu.

TrueUpdate Web Site

The TrueUpdate Web site is located at http://www.indigorose.com/products/trueupdate/. 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 us at www.indigorose.com for available support resources and policies. 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

TrueUpdate’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 TrueUpdate that are not officially supported in TrueUpdate. 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 TrueUpdate. 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 TrueUpdate'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 update. 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 application won't have a value when your application 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 updating files, UserName won't have a value before the updating stage.

    The same is true for using variables within a script. When you assign a value to a variable, the value doesn't get assigned to the variable until that line of script is performed; in other words, it's value is only available to the actions that come "later." If you try to use the variable in an action higher "up" in the same script, or use it in another event that happens "earlier," the variable either won't have a value yet, or it won't have the value you expected it to have, and your update will either generate an error or not behave as you intended. (This is why it's important to test your update 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 update, 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 TrueUpdate. 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 TrueUpdate, 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 TrueUpdate scripts easier to read.

Unless they are contained within a string, whitespace characters (like spaces and tabs) are completely ignored by the update 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.

TrueUpdate's action editor makes it easy to add this kind of indentation to your scripts. To indent your first line in a block, just press the tab key at the start of the line. This will move the cursor over by one "level" of indentation to the right. Then continue adding lines to the block. Whenever you press Enter on a line that is indented, the editor automatically positions your cursor at the same level of indentation on the next line.

Tip: You can even indent or unindent multiple lines at once, by selecting the lines and pressing Tab (to increase the level of indentation) or pressing Shift+Tab (to decrease the level of indentation).

Indentation is especially important when there are multiple levels involved. For example, here is a short script that has a nested for loop (i.e. one for loop inside another) and a bunch of if statements. First let's see the script with no indentation:

Debug.ShowWindow(true);
if bCount then
Debug.Print("\r\nCounting to a hundred five times...\r\n");
for j = 5, 1, -1
if(j == 1) then
Debug.Print("\r\n\r\nThis is the last time!\r\n");
else
Debug.Print("\r\n\r\n" .. j - 1 .. " more times to go!");
end
for i = 1, 100
Debug.Print(i.."\r\n");
if count == 50 then
Debug.Print("We're half way to a hundred!\r\n")
end
end
end
end

Now here's the script with standard block formatting:

Debug.ShowWindow(true);
if bCount then
Debug.Print("\r\nCounting to a hundred five times...\r\n");
for j = 5, 1, -1
if(j == 1) then
Debug.Print("\r\n\r\nThis is the last time!\r\n");
else
Debug.Print("\r\n\r\n" .. j - 1 .. " more times to go!");
end
for i = 1, 100
Debug.Print(i.."\r\n");
if count == 50 then
Debug.Print("We're half way to a hundred!\r\n")
end
end
end
end

See how the indentation makes it easier to see the different blocks?


Program Reference

Contents

Welcome to the TrueUpdate program reference!

Please select one of the following subjects:

  • Action Editor

  • Actions

  • Build Error Codes

  • Build Settings

  • Command Line Options

  • Controls

  • Languages

  • Miscellaneous

  • Preferences

  • Program Menus

  • Project File Properties

  • Project Settings

  • Project Wizard

  • Publish Wizard

  • Resources

  • Screens

  • Screen Types

  • Tools

  • Update Return Codes

  • Variables


Action Editor - Overview

Action Editor

Overview Interface Special Features Events

The action editor is a dialog where you can add actions or scripts to events in TrueUpdate.

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

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.


Action Editor - Interface

Action Editor

Overview Interface Special Features Events

Event Tabs

There is one tab for every event that the 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 or on the Script Editor page of the Preferences.

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.

Toggle Bookmark

Add or remove a bookmark from the current action script line. You can also access this menu item using Ctrl+F2.

Clear All

Remove all bookmarks from the current code window.

First

Jump to the first bookmarked action script line.

Previous

Jump to the previous bookmarked action script line. You can also access this menu item using Shift+F2.

Next

Jump to the next bookmarked action script line. You can also access this menu item using F2.

Last

Jump to the last bookmarked action script line.

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 of the Editor Settings dialog. The Editor Settings dialog can be accessed by selecting Tools > Editor Settings... or from the Advanced button.

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.

Record

Start recording a macro that can be played back at a later time. You can click the "End Recording" button on the Record Macro dialog to stop recording. To playback the recorded macro, you can select the Play option found underneath this menu option. You can also access this menu item using Ctrl+Shift+R.

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. You can also access this menu item using F12

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.

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

Editor Settings...

Opens the action editor's Editor Settings dialog where you can customize its settings. You can also access this menu item using Ctrl+Enter.


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 design-time constant, 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.

Quick Scripts

A menu containing a variety of code templates you can add to the code window. You can find further information on code structures in the Scripting Guide. You can access this feature both from the right-click menu and from the Script program menu.

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

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 or from the Script Editor page of the Preferences dialog.


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. 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 contain special event variables that are local to the event and contain more information about the event.

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 update, or by re-setting the control's text using the Dlg***.SetProperties actions.

On Start

This event is fired from a progress screen to start its progress actions.


Actions - Overview

Actions

Overview Alphabetical List Error Codes

What are actions?

Actions are the commands that your TrueUpdate application can perform at run time. Each action is a discrete instruction that tells the update 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 update do stuff.

And there's a lot of stuff your update can do! (Just have a look at the alphabetical list of actions.)

When do actions happen?

Actions are always triggered by either screen events, or run on a script tab. An event is something that occurs at run time while the user is proceeding through your update. This includes things like clicking on the next button on a screen (the "On Next" screen event). Script tabs contain action script that are run at certain points of an update. TrueUpdate contains the two script tabs, Client Script and Server Script . Each script tab behaves like a regular action editor. You can also add custom script tabs to your project by selecting Script > New from the program menu.

Where do I find these screen events and script tabs?

Events will appear as tabs on the action editor of a screen's properties dialog. Below you will find an example of screen events:

The Client Script and Server Script tabs can be found on the main design window as seen below:

How do I add an action?

As mentioned above, actions can be added in a couple places.
Actions can be added to screen events by selecting the actions tab of the screen's properties dialog.
Actions can be added to script tabs by selecting Script > Action Wizard... from the program menu, or by right-clicking in the code window of the script tab and selecting Action Wizard.

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

Application.GetUpdateLanguage

Application.GetWndHandle

Application.LoadActionPlugin

Application.LoadScript

Application.LoadValue

Application.Minimize

Application.Restore

Application.RunScriptFile

Application.SaveValue

Application.SetUpdateLanguage

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

Dlgeditfield

DlgEditField.GetProperties

DlgEditField.SetProperties

DlgGROUPBOX

DlgGroupBox.GetProperties

DlgGroupBox.SetProperties

DlgListbox

DlgListBox.AddItem

DlgListBox.DeleteItem

DlgListBox.FindItem

DlgListBox.GetCount

DlgListBox.GetItemProperties

DlgListBox.GetProperties

DlgListBox.GetSelected

DlgListBox.GetSelectedCount

DlgListBox.InsertItem

DlgListBox.SetItemProperties

DlgListBox.SetProperties

DlgListBox.SetUpdate

DlgProgressbar

DlgProgressBar.GetPos

DlgProgressBar.GetProperties

DlgProgressBar.GetRange

DlgProgressBar.SetPos

DlgProgressBar.SetProperties

DlgProgressBar.SetRange

DlgProgressBar.SetStep

DlgProgressBar.Step

Dlgradiobutton

DlgRadioButton.GetProperties

DlgRadioButton.SetProperties

Dlgscrollingtext

DlgScrollingText.AppendLine

DlgScrollingText.GetProperties

DlgScrollingText.SetProperties

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

FTPWI

FTPWI.Download

FTPWI.GetErrorInfo

FTPWI.GetFileSize

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

Screen.SetFocus

Screen.SetLocalizedString

Screen.Show

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

Trueupdate

TrueUpdate.GetLocalizedString

TrueUpdate.GetServerFile

TrueUpdate.GetUpdateServerList

TrueUpdate.LoadServerFile

TrueUpdate.RunScript

TrueUpdate.SetLocalizedString

TrueUpdate.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 update and returns an optional return code.

Tip: You can use this action to exit the update process at any point.

Parameters

ReturnCode

(number) The optional return code you want to set for the update'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.

Tip: You can use this action to exit the update process at any point.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


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

table Application.GetUpdateLanguage (

)

Description

Returns a table containing the primary and secondary language ID that is being used by your update. The value returned by Application.GetUpdateLanguage 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 update.

Note: This action may return a different result than System.GetDefaultLangID.

Parameters

None.

Returns

(table) A table containing the current update 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.GetWndHandle

number Application.GetWndHandle (

)

Description

Returns the numeric window handle for the main update 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 update, whether a background window is visible or not.

Parameters

None.

Returns

(number) The numeric window handle for the update. If an error occurs, -1 will be returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Application.LoadActionPlugin

Application.LoadActionPlugin (

string Filename )

Description

Loads an action plugin file (.lmd).

Note: Normally you would choose Project > Plugins... to add an action plugin. This action is only intended to handle special situations where you need more control over when the plugin is loaded.

Action plugins allow you to extend the functionality of TrueUpdate with new actions. Refer to the action plugin's documentation for information on what features it adds and how to use them.

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 TrueUpdate 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 update window to the task bar.

Note: If the update's Taskbar Visibility is set to "Hidden" this action will have no effect.

Note: If the update is set to minimized before a screen is shown, showing a screen will "restore" the application.

Parameters

None.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.Restore

Application.Restore (

)

Description

Restores the update'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 update'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 TrueUpdate 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.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.SetUpdateLanguage

Application.SetUpdateLanguage (

number Primary,

number Secondary )

Description

Sets the specified language to be the update 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 update.

Secondary

(number) The secondary language ID of the language (in decimal format) you want to set for the update.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Application.Sleep

Application.Sleep (

number Time )

Description

Causes the update to sleep for a desired period of time.

Note: While sleeping, the update will not respond to mouse movements, clicks, or key presses. This applies to every aspect of the update, including but not limited to the Cancel button.

Parameters

Time

(number) The time to sleep, in milliseconds.

Tip: 1000 milliseconds = 1 second

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


Crypto.Base64DecodeFromFile

Crypto.Base64DecodeFromFile (

string Source,

string Destination )

Description

Decodes a base64-encoded text file and stores the result as a binary file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Source

(string) The full path to the base64-encoded text file that you want to decode.

Destination

(string) The full path and filename for the decoded binary file.

Returns

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.


Crypto.Base64DecodeFromString

Crypto.Base64DecodeFromString (

string Text,

string Filename )

Description

Decodes a base64-encoded string and stores the result as a binary file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Text

(string) The base64-encoded text that you want to decode.

Filename

(string) The full path and filename for the decoded binary file.

Returns

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.


Crypto.Base64EncodeToFile

Crypto.Base64EncodeToFile (

string Source,

string Destination,

number LineLen = 76 )

Description

Stores the contents of a binary file as a base64-encoded text file.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Source

(string) The full path to the file that you want to encode.

Destination

(string) The full path and filename for the base64-encoded file.

LineLen

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 76.

Returns

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.


Crypto.Base64EncodeToString

string Crypto.Base64EncodeToString (

string Source,

number LineLen = 76 )

Description

Returns the contents of a binary file as a base64-encoded string.

Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Source

(string) The full path to the file that you want to encode.

LineLen

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 76.

Returns

(string) The contents of the specified binary file as a base64-encoded string. If the data cannot be encoded or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError() to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.BlowfishDecrypt

Crypto.BlowfishDecrypt (

string Source,

string Destination,

string Key )

Description

Creates a decrypted copy of a blowfish-encrypted file.

Parameters

Source

(string) The full path to the file that you want to decrypt.

Destination

(string) The full path and filename for the decrypted file.

Key

(string) The secret key that the data was decrypted with.

Returns

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.


Crypto.BlowfishDecryptString

string Crypto.BlowfishDecryptString (

string Text,

string Key )

Description

Decrypts a string that was encrypted using the Crypto.BlowfishEncryptString action. (Decodes a base64-encoded string and decrypts the blowfish-encrypted data.)

Tip: You do not have to Base64Decode the string first, simply pass this action any string encoded using the Crypto.BlowfishEncryptString.

Note: Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Text

(string) The string that you want to decrypt.

Key

(string) The secret key that the data was encrypted with.

Returns

(string) The decrypted version of a string that was encrypted with a Crypto.BlowfishEncryptString action. If the data cannot be decrypted or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.BlowfishEncrypt

Crypto.BlowfishEncrypt (

string Source,

string Destination,

string Key )

Description

Creates a blowfish-encrypted copy of a file.

Parameters

Source

(string) The full path to the file that you want to encrypt.

Destination

(string) The full path and filename for the blowfish-encrypted file.

Key

(string) The secret key to encrypt the data with.

Returns

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.


Crypto.BlowfishEncryptString

string Crypto.BlowfishEncryptString (

string Text,

string Key,

number LineLen = 0 )

Description

Blowfish encrypts a string and returns a base64-encoded string containing the encrypted data.

Note: Base64 encoding is the process of encoding arbitrary data as plain ASCII text. One common use for this type of encoding is sending files through email. It is one of the techniques employed by the MIME standard to send data other than plain ASCII text.

Parameters

Text

(string) The string that you want to encrypt.

Key

(string) The secret key to encrypt the data with.

LineLen

(number) The maximum line length for the base64-encoded text, in columns. (Use 0 for no line breaks.) The default value is 0.

Returns

(string) A base64-encoded string containing the encrypted data. If the data cannot be encrypted or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the script editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.MD5DigestFromFile

string Crypto.MD5DigestFromFile (

string Filename )

Description

Creates an MD5 message digest for a given file.

Parameters

Filename

(string) The full path to the file whose MD5 digest you want to calculate.

Note: The file can be of any type (binary or ascii).

Returns

(string) The message digest that was calculated for the file. If the message digest cannot be calculated or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.MD5DigestFromString

string Crypto.MD5DigestFromString (

string Text )

Description

Creates an MD5 message digest for a given text string.

An MD5 message digest is a 128-bit "fingerprint" or digital signature, represented by a string of 32 hex digits. Every unique string of text is guaranteed to produce a unique message digest. More importantly, it is virtually impossible to determine the original string from the digest. In other words, the MD5 calculation only works in one direction. This makes it extremely useful for storing passwords.

Instead of storing a password in plain text, you should store its MD5 digest instead. When the user enters a password, calculate the MD5 digest for the text that they entered, and compare that to the MD5 digest that was stored. If it is identical to the stored digest, then the user entered the correct password.

Since there is no way to get from the digest back to the original password, it doesn't matter if anyone sees the digest.

Note: MD5 isn't a substitute for secure passwords. Using an insecure password like "sneeze" or "equine" can still leave your application open to so-called "dictionary attacks," where the hacker simply tries the MD5 digest for every word in the dictionary. Be sure to use secure passwords like "sationicat59" or "b$fer@fe!23."

Tip: A good way to defeat dictionary attacks when using user-supplied passwords is to append a non-alphabetic string to all passwords. For example, simply append "$!%" to the end of any password before generating the MD5 digest. This way, even a really bad password like "password" will be relatively safe from dictionary attacks.

Parameters

Text

(string) The text to create the message digest for.

Returns

(string) The message digest that was calculated for the given text. If the message digest cannot be calculated or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Crypto.Rot13

string Crypto.Rot13 (

string Text )

Description

Applies a simple Ceaser-cypher ("rot13") encryption to the text.

The simple Caesar-cypher encryption replaces each English letter with the one 13 places forward or back along the alphabet, so that "Indigo Rose is cool!" becomes "Vaqvtb Ebfr vf pbby!" In other words, it "rotates" the alphabet ahead 13 characters. Most Usenet news reading and posting programs include a rot13 feature to hide text from plain sight so the user must choose to view it. (For example, to hide "spoilers" -- information that gives away some secret that readers might not want to know if they haven't already read the book, played the game, etc.)

A nice feature of rot13 is that the same action is used to encrypt and decrypt the text.

Parameters

Text

(string) The text that you want to encrypt (or decrypt).

Returns

(string) The encrypted (or decrypted) text. If the text cannot be encrypted (or decrypted) or some other error occurs, an empty string ("") is returned. You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Debug.Clear

Debug.Clear (

)

Description

Clears the contents of the debug window.

Parameters

None.

Returns

Nothing.


Debug.GetEventContext

string Debug.GetEventContext (

)

Description

Returns a string describing the current event context, e.g. "Welcome > On Next".

Parameters

None.

Returns

(string) A string describing the current event context.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Debug.GetTraceMode

boolean Debug.GetTraceMode (

)

Description

Returns the current debug trace mode.

Parameters

None.

Returns

(boolean) True if trace mode is on, false if trace mode is off.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


Debug.Print

Debug.Print (

string Text )

Description

Appends text to the bottom of the debug window.

Parameters

Text

(string) The text to add to the debug window.

Returns

Nothing.


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

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.

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.

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 TrueUpdate'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 TrueUpdate, 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 | TrueUpdate will interpret the function's return value as a 16-bit integer (int).
DLL_RETURN_TYPE_LONG | 1 | TrueUpdate will interpret the function's return value as a 32-bit integer (long).
DLL_RETURN_TYPE_STRING | 2 | TrueUpdate 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 TrueUpdate 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 installer 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 install:

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 install and uninstall 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 moved.

Destination

(string) The destination path for file being moved.

Copied

(number) The number of bytes moved so far.

Total

(number) The total bytes that will be moved.

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

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.

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 and Windows XP. 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 update.

Parameters

None.

Returns

(string) The path to the "current folder" (working directory) for the update. 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 update'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.


FTPWI.Download

FTPWI.Download (

string URL,

string Filename,

string Username = "anonymous",

string Password = "guest@",

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 21,

boolean PassiveMode = true,

function CallbackFunction = nil )

Description

Downloads a file from an FTP site using FTP (file transfer protocol).

Parameters

URL

(string) The full ftp address to the file you want to download. For example, ftp://ftp.myftpsite.com/updates/myfile.txt.

Filename

(string) The destination path and filename of the file you want to download. For example, C:\\MyFolder\\patch.zip.

Username

(string) The name to use to log into the FTP site. The default for anonymous FTP is "anonymous".

Password

(string) The password for the FTP site that goes with the FTP Username. For anonymous FTP, use your email address or the password default "guest@".

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 21 is standard for FTP.

PassiveMode

(boolean) Use passive/firewall mode when downloading the file. Passive mode (also known as "firewall mode") is required whenever you need to transfer files to or from an FTP server from behind a firewall. Passing the default value true enables passive mode and passing false disables it.

Normally, your computer makes a connection to an FTP server, and the FTP server responds by opening a connection back to your computer. This return connection won't work if your computer can't be reached directly from the Internet. In passive mode, both connections are made from your computer, so the FTP server doesn't have to do any connecting—it just waits passively for your computer to make both of the connections to it.

Most servers support passive mode connections, so it's generally best to leave this setting enabled.

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.


FTPWI.GetErrorInfo

table FTPWI.GetErrorInfo (

)

Description

Retrieves FTP specific information about the last error that occurred.

For example, if you perform an FTPWI.Download and an error occurs, you can use this action to retrieve FTP information about that error.

Parameters

None.

Returns

(table) A table containing the FTP 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.

You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When adding an action with the action editor, you can use this field to specify a variable that the return value will be stored in.


FTPWI.GetFileSize

number FTPWI.GetFileSize (

string URL,

string Username = "anonymous",

string Password = "guest@",

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 21,

boolean PassiveMode = true,

function CallbackFunction = nil )

Description

Gets the size of a file (in bytes) located on an FTP site.

Parameters

URL

(string) The full ftp address to the file you want the size of. For example, ftp://ftp.myftpsite.com/updates/myfile.txt.

Username

(string) The name to use to log into the FTP site. The default for anonymous FTP is "anonymous".

Password

(string) The password for the FTP site that goes with the FTP Username. For anonymous FTP, use your email address or the password default "guest@".

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 FTPWI 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 21 is standard for FTP.

PassiveMode

(boolean) Use passive/firewall mode when accessing the file. Passive mode (also known as "firewall mode") is required whenever you need to transfer files to or from an FTP server from behind a firewall. Passing the default value true enables passive mode and passing false disables it.

Normally, your computer makes a connection to an FTP server, and the FTP server responds by opening a connection back to your computer. This return connection won't work if your computer can't be reached directly from the Internet. In passive mode, both connections are made from your computer, so the FTP server doesn't have to do any connecting—it just waits passively for your computer to make both of the connections to it.

Most servers support passive mode connections, so it's generally best to leave this setting enabled.

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 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 FTP 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.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 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.GetConnectionState

table HTTP.GetConnectionState (

)

Description

Retrieves the connected state of the local system. connection state

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\\0update=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 install. 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 install 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 install. 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. TrueUpdate 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, TrueUpdate 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 in the update and causes Screen.Show to return SR_LISTCOMPLETE.

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
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 update given a screen name.

Note: This action can be used to jump forward or backward in the update, however the target screen must be located in the current screen list.

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 current screen list according to the order in the screen manager at design time.

Note: If you have reached the end of a screen list, this action causes Screen.Show to return SR_LISTCOMPLETE.

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 current screen list according to their order in either the Client Screens or Server Screens panel 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.Return

Screen.Return (

number ReturnCode )

Description

Sets the return value of a screen. The return value of a screen is the value that is returned by Screen.Show.

Note: This action will cause the current script to end, so any actions after it will not be executed.

Parameters

ReturnCode

(number) The return code you want to set for the screen. Generally this should be one of the constants below (but doesn't have to be):

CONSTANT | VALUE | DESCRIPTION
SR_NEXT | 0 | This code can be used to identify that the screen was successful. Normally this can be found on the On Next event of a screen.
SR_PREV | 1 | This code can be used to identify that the user pressed the Back button on a screen. Normally this can be found on the On Back event of a screen.
SR_CANCEL | 2 | This code can be used to identify that the user clicked the Cancel button on a screen, or closed the screen. Normally this can be found on the On Cancel event of a screen.
SR_FAIL | 3 | This code can be used to identify that the screen failed in some way.
SR_SUCCESS | 4 | This code can be used to identify that the screen succeeded.

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

number Screen.Show (

string ListName,

string FirstScreen = "" )

Description

Shows the screens of a given screen list and returns the list's return code. Return codes can be generated from a screen using the Screen.Return action or the Screen.Next action. You can also specify the first screen to show in the given list.

Note: Since only one screen list can be shown at a time, this action can only be called from a script tab. Using this action on a screen event will result in an error.

Parameters

ListName

(string) The name of the screen list you want to show.

FirstScreen

(string) The first screen in the specified list you want to show. Leave this parameter blank ("") if you want to show the first screen in the screen list.

Returns

(number) The numeric return code of the specified screen. A return code can be any value set through the Screen.Return or Screen.Next action, however normally one of the following values are returned:

CONSTANT | VALUE | DESCRIPTION
SR_NEXT | 0 | This code is normally used to identify that the screen was successful. Normally this can be found on the On Next event of a screen.
SR_PREV | 1 | This code is normally used to identify that the user pressed the Back button on a screen. Normally this can be found on the On Back event of a screen.
SR_CANCEL | 2 | This code is normally used to identify that the user clicked the Cancel button on a screen, or closed the screen. Normally this can be found on the On Cancel event of a screen.
SR_FAIL | 3 | This code is normally used to identify that the screen failed in some way.
SR_SUCCESS | 4 | This code can be used to identify that the screen succeeded.
SR_LISTCOMPLETE | 10 | This code is returned by the Screen.Next action when the end of a screen list has been reached.

You can use Application.GetLastError to determine whether this action failed, and why.

ResultVariable

When 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.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 update. 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.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.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.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\\TrueUpdate 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 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_ULTIMATE | 1 | Ultimate Edition
PRODUCT_HOME_BASIC | 2 | Home Basic Edition
PRODUCT_HOME_PREMIUM | 3 | Home Premium Edition
PRODUCT_ENTERPRISE | 4 | Enterprise Edition
PRODUCT_HOME_BASIC_N | 5 | Home Basic Edition
PRODUCT_BUSINESS | 6 | Business Edition
PRODUCT_STANDARD_SERVER | 7 | Server Standard Edition (full installation)
PRODUCT_DATACENTER_SERVER | 8 | Server Datacenter Edition (full installation)
PRODUCT_SMALLBUSINESS_SERVER | 9 | Small Business Server
PRODUCT_ENTERPRISE_SERVER | 10 | Server Enterprise Edition (full installation)
PRODUCT_STARTER | 11 | Starter Edition
PRODUCT_DATACENTER_SERVER_CORE | 12 | Server Datacenter Edition (core installation)
PRODUCT_STANDARD_SERVER_CORE | 13 | Server Standard Edition (core installation)
PRODUCT_ENTERPRISE_SERVER_CORE | 14 | Server Enterprise Edition (core installation)
PRODUCT_ENTERPRISE_SERVER_IA64 | 15 | Server Enterprise Edition for Itanium-based Systems
PRODUCT_BUSINESS_N | 16 | Business Edition
PRODUCT_WEB_SERVER | 17 | Web Server Edition (full installation)
PRODUCT_CLUSTER_SERVER | 18 | Cluster Server Edition
PRODUCT_HOME_SERVER | 19 | Home Server Edition
PRODUCT_STORAGE_EXPRESS_SERVER | 20 | Storage Server Express Edition
PRODUCT_STORAGE_STANDARD_SERVER | 21 | Storage Server Standard Edition
PRODUCT_STORAGE_WORKGROUP_SERVER | 22 | Storage Server Workgroup Edition
PRODUCT_STORAGE_ENTERPRISE_SERVER | 23 | Storage Server Express Edition
PRODUCT_SERVER_FOR_SMALLBUSINESS | 24 | Server for Small Business Edition
PRODUCT_SMALLBUSINESS_SERVER_PREMIUM | 25 | Small Business Server Premium Edition
PRODUCT_HOME_PREMIUM_N | 26 | Home Premium Edition
PRODUCT_ENTERPRISE_N | 27 | Enterprise Edition
PRODUCT_ULTIMATE_N | 28 | Ultimate Edition
PRODUCT_WEB_SERVER_CORE | 29 | Web Server Edition (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_STANDARD_SERVER_V | 36 | Server Standard Edition without Hyper-V (full installation)
PRODUCT_DATACENTER_SERVER_V | 37 | Server Datacenter Edition without Hyper-V (full installation)
PRODUCT_ENTERPRISE_SERVER_V | 38 | Server Enterprise Edition without Hyper-V (full installation)
PRODUCT_DATACENTER_SERVER_CORE_V | 39 | Server Datacenter Edition without Hyper-V (core installation)
PRODUCT_STANDARD_SERVER_CORE_V | 40 | Server Standard Edition without Hyper-V (core installation)
PRODUCT_ENTERPRISE_SERVER_CORE_V | 41 | Server Enterprise Edition without Hyper-V (core installation)
PRODUCT_HYPERV | 42 | Hyper-V Server
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).
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 8, Windows 7, Windows Vista, Windows XP, Windows 2000 Professional, or Windows NT Workstation 4.0 SP6 and later.
Server: Requires 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 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 "Longhorn", Datacenter Edition, 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 "Longhorn", 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/7/8 Home Premium, Windows Vista/7/8 Home Basic, or Windows XP Home Edition is installed. If it is installed, the value true is returned. If it is not installed, false is returned.
SingleUserTerminalService | boolean | Whether or not Terminal Services is installed, but only one interactive session is supported. If only one interactive session is supported, the value true is returned. If Terminal Services is not installed, or supports more than one interactive session, false is returned.
SmallBusiness | boolean | Whether or not Microsoft Small Business Server was once installed on the system, but may have been upgraded to another version of Windows. If it was installed at some point, the value true is returned. If it was never installed, false is returned.
SmallBusinessRestricted | boolean | Whether or not Microsoft Small Business Server is installed with the restrictive client license in force. If it is installed with the restrictive client license in force, the value true is returned. If it is not, false is returned.
Terminal | boolean | Whether or not Terminal Services is installed. If it is installed, the value true is returned. If it is not installed, false is returned.
Communications | boolean | Whether or not Communication components installed. If they are installed, the value true is returned. If they are not installed, false is returned.
Server2003R2 | boolean | Whether or not the operating system is Windows 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/8 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 or Windows 8 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 Updates 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 and later operating systems, the result will be the same as the normal administrator check IsAdmin as mentioned above.

Note: See Updates On Windows Vista 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, you would use this flag when a user cancels the update. 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.


TrueUpdate.GetLocalizedString

string TrueUpdate.GetLocalizedString (

string StringID )

Description

Gets the localized text (based on current update language) of the global (opposed to per-screen) strings.

Note: These are the strings defined in ...\TrueUpdate 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.


TrueUpdate.GetServerFile

boolean TrueUpdate.GetServerFile (

string ServerID,

boolean ShowRestartDialog = true,

function CallbackFunction = nil )

Description

Attempts to download and load the server configuration files from a specific TrueUpdate Server.

Note: This action also updates the client files if needed. If the client files require updating, a notification dialog will be shown, the update process is restarted, and the global variable _ClientRestarted is set to true.

Parameters

ServerID

(string) The Name/ID of the TrueUpdate Server you want to get the server configuration files from.

ShowRestartDialog

(boolean) Whether to show the restart dialog if the client needs to be restarted when a new client executable or client .dat file is availalable:

VALUE | DESCRIPTION
true | Show a dialog notifying that the client needs to be restarted. (Default)
false | Restart the client without a notification dialog.

CallbackFunction

(function) The name of a function that will be called whenever progress is made in the download operation of the server configuration files. (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.

UpdateInfo

(table) A table containing update information for the new client files indexed by the following categories. If the client files do not need to be updated, nil is returned.

KEY | TYPE | DESCRIPTION
UpdateType | number | The type of update being performed. If 0 is returned, the client executable (.ts3) is being downloaded. If 1 is returned, the client data file (.ts2) is being downloaded. You can access this value using tb.UpdateType.
UpdateFile | string | The full path to the current file that is being downloaded. For example: ftp://myftp.ftp/files/update.ts2. You can access this value using tb.UpdateFile.
UpdateVersion | string | The version of the client executable that is being downloaded. You can access this value using tb.UpdateVersion.

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

(boolean) True if the server configuration file was downloaded and loaded successfully, or false if it was 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.


TrueUpdate.GetUpdateServerList

table TrueUpdate.GetUpdateServerList (

)

Description

Returns a numerically indexed table (one-based) containing the Name/IDs of the TrueUpdate Servers published to the client.

Parameters

None.

Returns

(table) A numerically indexed table (one-based) containing the Name/IDs of the TrueUpdate Servers published to the client. If there are no TrueUpdate Servers 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.


TrueUpdate.LoadServerFile

boolean TrueUpdate.LoadServerFile (

string ServerFilePath,

string Key )

Description

Loads a server configuration file given its local path and encryption key.

Note: The server configuration file (.ts1) must already be downloaded and available locally.

Parameters

ServerFilePath

(string) The full path to the server configuration file (.ts1) you want to load. For example: _SourceFolder.."\\MyServerFile.ts1".

Key

(string) The encryption key to use to decrypt the specified server configuration file.

Note: The encryption key for the project can be found on the Options tab of the Project Settings dialog.

Returns

(boolean) True if the server configuration file was loaded successfully, or false if it was 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.


TrueUpdate.RunScript

TrueUpdate.RunScript (

string ScriptID )

Description

Runs a server configuration file's script given its script tab name.

Parameters

ScriptID

(string) The name of the server configuration file script you want to run. This is the name that is shown on tab where the script is located.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


TrueUpdate.SetLocalizedString

TrueUpdate.SetLocalizedString (

string StringID,

string Text )

Description

Sets the text of a string ID in the current language for the update.

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.


TrueUpdate.WriteToLogFile

TrueUpdate.WriteToLogFile (

string Text,

boolean AddTimestamp = true )

Description

Writes a string of text to the update 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 log file option is not set in the update, this action will not generate an error. Instead, it will simply have no effect. You can enable the creation of an update log file on the Options tab of the Project Settings dialog.

Parameters

Text

(string) The text you want to output to the log file.

AddTimestamp

(boolean) Whether to prepend a time stamp to the Text. Choose from:

VALUE | DESCRIPTION
true | Prepend a time stamp to the text in the form [06/18/2004 13:17:48]. (Default)
false | Don't prepend a time stamp.

Returns

Nothing. You can use Application.GetLastError to determine whether this action failed, and why.


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 TrueUpdate update 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 TrueUpdate:

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/FTP 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

(3600-3699) TrueUpdate Action 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/FTP 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."

2509

"An error occurred while trying to open an FTP file."

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 update."

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

2822

"Error, only one screen list at a time can be shown."

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

TrueUpdate Action Related (3600-3699)

3600

"Error, no server file has been loaded."

3601

"The script could not be found in the current server file."

3602

"An error occurred while executing the server script."

3603

"An error occurred when trying to read the server file. (Mismatched encryption key?)"

3604

"The server file was not found in the location specified."

3605

"An error occurred when trying to download the server file."

3606

"The server file was not the expected size."

3607

"An error occurred when trying to open the local file."

3608

"An internal error occurred while trying to download the server file."

3609

"An error occurred while trying to create the internet session."

3610

"An error occurred while trying to create the internet connection."

3611

"An error occurred while trying to open the HTTP file."

3612

"A send request failed while trying to download the server file."

3613

"An error occurred while trying to open the local file."

3614

"The incorrect status was returned by the server."

3615

"An error occurred while trying to read the Internet file."

3616

"An error occurred while trying to write to the local file."

3617

"The download of the server file was cancelled."

3618

"An error occurred when trying to open the FTP file."

3619

"An error occurred when trying to write to memory. (Out of memory?)"

3620

"An error occurred when trying to set the proxy username."

3621

"An error occurred when trying to set the proxy password."

3622

"The request could not be understood by the server. (Bad Syntax)"

3623

"Access is forbidden."

3624

"The requested URL was not found on the server."

Note: If all of your files seem to be uploaded properly, check to make sure that the *.ts* extensions are part of the MIME types list on your server.

3625

"An internal server error has occurred."

3626

"The server is at full capacity."

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


Build Settings - Overview

Build Settings

Overview Output Upload Constants Code Signing Resources Pre/Post Build

The Build Settings dialog is where you can make decisions that control the generation and publishing of your final update files. Some of these settings include: the location you wish to output the TrueUpdate client files and server configuration files; the server locations to publish to; design-time constants that you wish to recognize during the build process; Code Signing settings to sign the client executable; custom resource stamping options; and any programs you wish to run before or after the build process.

To access the Build Settings dialog, choose Publish > Settings... from the program menu.

The Build Settings contain the following six categories:

  • Output

  • Upload

  • Constants

  • Code Signing

  • Resources

  • Pre/Post Build


Output

Build Settings

Overview Output Upload Constants Code Signing Resources Pre/Post Build

Output Settings

Output folder:

The directory that you want the TrueUpdate client and server configuration files saved to when it is finished building. You can click the Browse button to select an output folder. There are five files in total that will be saved to this folder, *.exe, *.dat, *.ts1, *.ts2 and *.ts3.

TrueUpdate Client filename:

The name you want to give your TrueUpdate client executable file. This can be update.exe, myupdate.exe or anything else that you want. The data file will also use this file name when it is generated. For example, if your filename was myupdate.exe, the data file would be named myupdate.dat.

Server files prefix:

The prefix that will be used for all of the server configuration files that are generated during the build. For example, if the prefix is myproduct, the files generated will be myproduct.ts1, myproduct.ts2 and myproduct.ts3. You can click the Change button to change the server file prefix. The recommended format is all lowercase alphabetic characters containing no spaces.

Note: Changing the server files prefix after your client has been published will break compatibility between the server data and the TrueUpdate client. Any changes to the prefix should generally be done before distributing your update.

Compress client executable

Compress the client executable during the build process using UPX compression. Generally compressing the file reduces its size by about 50%. You may find an uncompressed format useful if you need to do something to the file such as wrap it using a third party tool.

Note: Changing this setting after the initial release of the client executable will cause the distributed client executable to update itself when run.


Upload

Build Settings

Overview Output Upload Constants Code Signing Resources Pre/Post Build

The Upload tab is where you can configure all of the locations that you want to automatically publish your server configuration files to when you build. There are several options for publishing your server configuration files such as FTP, SFTP or by copying the file. Normally these locations will be the locations that were configured on the TrueUpdate Servers tab of the Project Settings dialog.

Note: If while running your update, you receive error 3624 and you have already confirmed that all of the server configuration files have been properly uploaded, make sure that the *.ts* extensions are part of the MIME types list on the server.

Note: When you publish automatically through TrueUpdate, there is an additional file that is uploaded that the TrueUpdate publisher uses to determine whether or not new copies of each file needs to be uploaded. This prevents unnecessary uploading if certain server configuration files have not changed. This file's name is composed of the server files prefix with a .tsx file extension. This file is only used by the TrueUpdate design environment and is not used at run time.

Automatic upload locations:

Name

The unique names of each upload location currently defined in your project that can be automatically published to. Each list item contains a checkbox next to it showing which upload locations will be published to on the next build. If you do not wish to publish to a particular upload location, you can uncheck the box next to the name.

Location

The upload locations that are currently configured in the project.

Type

The upload methods currently configured for each of the upload locations (eg. Copy, FTP, or SFTP).

Last Upload

The last time each upload location was published to, in the format MM/DD/YYYY Time. If the upload location has never been published to, "Never" will be displayed.

Add

Add a new upload location to the upload locations list. The following upload types are available:

FTP

Upload the server configuration files to the upload location using FTP when publishing. This opens the Upload Location (FTP) dialog where you can configure its settings.

SFTP

Upload the server configuration files to the upload location using SFTP when publishing. SFTP is similar to FTP but transfers data securely over SSH layer using AES, DES, and BLOWFISH encryption. This opens the Upload Location (SFTP) dialog where you can configure its settings.

File Copy

Copy the server configuration files to a LAN/local folder when publishing. This opens the Upload Location (File Copy) dialog where you can browse for the destination folder.

Remove

Remove the selected location from the upload locations list.

Edit

Edit the properties of the selected upload location. This opens the appropriate Upload Location settings dialog.


Constants

Build Settings

Overview Output Upload Constants Code Signing Resources Pre/Post Build

Design-timeConstants

A list of all of the custom design-time constants in the current project.

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 the time you build. At build time, the name of each 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 project.

Remove

Remove the selected design-time constant from the current project.

Rename

Rename the selected design-time constant from the current project.


Code Signing

Build Settings

Overview Output Upload Constants Code Signing Resources Pre/Post Build

Tip: See the Code Signing section of the preferences (Edit > Preferences, Code Signing) to configure default values when creating new projects.

Note: Changing any of the setting below after the initial release of the client executable will cause the distributed client executable to update itself when run.

Tip: If you want full control over the how the update 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, TrueUpdate automatically passes the option "sign".

CodeSign updates

If checked, the update client 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 update client. Choose from:

SignTool.exe

Use SignTool.exe to digitally sign the client update 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 client update 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 client update 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 client 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. TrueUpdate automatically passes the "sign" argument when "SignTool.exe" is the selected tool.


Resources

Build Settings

Overview Output Upload Constants Code Signing Resources Pre/Post Build

Note: Changing any of the setting below after the initial release of the client executable will cause the distributed client executable to update itself when run.

Custom Icon

Note: This feature requires the update to be built on Windows 2000 or greater.

Use custom icon

If checked, you can use a custom icon for the client update executable.

Path to local icon file:

The full path and filename of the icon file (.ico) to use for the client update executable. You can click the Browse button to select an icon file.

Custom Resource Information

Note: This feature requires the update to be built on Windows 2000 or greater.

Note: TrueUpdate reserves the 'Private Build' resource field for important program information. You should never modify this resource information manually.

Stamp executable with custom information

If checked, you can stamp the client update executable with your own custom information.

Product version:

The product version. For example, "1.0.0.19". If you leave out any digits they will be replaced with zeros.

Product name:

The name of the product. For example, "My Nifty Application."

Company name:

Your company name. For example, "Indigo Rose Software."

File description:

A short description about the purpose of the published executable. For example, "My Nifty Application runtime."

Internal name:

The internal name of the product. Usually the same as the Product name.

Trademarks:

Trademark notices for the product.

Copyright:

A copyright notice for the product. For example, "Copyright © 2012 - Indigo Rose Software."

Special build:

Any 'special build' notes that may apply.

Tip: In order for the TrueUpdate client to function correctly, a section of its resources must be modified when publishing. If you are trying to publish on an unsupported operating system below Windows 2000, or are having problems, you can set a hidden preference that will allow a build to complete with warnings, instead of fatal errors when updating its resources. Open your TrueUpdate preferences file (see the Folders preference for its current location) in a text editor and locate the XML tag "SupressResourceStampError". Then change its value from 0 to 1. While this allows you to publish, skipping this crucial step means that the client will always require updating itself when it is run.


Pre/Post Build

Build Settings

Overview Output Upload Constants Code Signing Resources Pre/Post Build

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 update files are generated. You can click the Browse button to select the file you want to run.

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 TrueUpdate wait until after the program has finished running before it continues. If not checked, TrueUpdate will simply start the program and continue with the build process.

Tip: You can have the program run in the Run Before Build settings create an INI file of build constants that will be applied to the build. The INI file must have the same path and filename as the project file, but with the .ini file extension. So, for example, if the project being built is "C:\Projects\MyProject.tu2" then the INI file must be called "C:\Projects\MyProject.ini". The INI file should have a section called "Constants" where the build constant name equals the value. For example:

[Constants]
#MYVALUE#=This is my value.
#CUSTOMERNAME#=Bob

Note that this INI file will only be used if there was a pre-build program run.

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 update files are generated. You can click the Browse button to select the file you want to run.

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 TrueUpdate wait until after the program has finished running before it continues. If not checked, TrueUpdate will simply start the program and continue without waiting.


Controls - Overview

Controls

Overview Control Types

Controls are interactive objects that exist on screens to collect or present information. Some examples of controls are buttons, edit fields and combo boxes, each of which have their own unique features.

In order to respond to user interaction, each type of control fires unique notification messages to signal what type of interaction occurred with the control. Any control message that is fired from the screen can be detected on the On Ctrl Message event of the screen. This allows you to respond with actions at that exact moment.

Each control on a screen contains a unique identifier called a Control ID, for example CTRL_BUTTON_NEXT. This ID is used to determine exactly which control fired the notification message and which control message was fired. An example of a control message is MSGID_CLICKED.

In most cases, it is not necessary to manually interact with controls since much of the functionality is built into the available screen templates. However, sometimes further customization is required and controls offer the power and flexibility to accomplish a wide range of dynamic designs.


Control Types

Controls

Overview Control Types

TrueUpdate'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 TrueUpdate:

  • 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 update 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


Overview

Languages

Overview Settings

Many developers distribute and update their applications in locations around the world whose native languages differ. For this reason, it is often desired to present the update's instructions in different languages based upon the language currently defined in their Operating System's Regional Settings.

TrueUpdate 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 update and what they would like to present to the user in those cases.

Language text is mainly used for messages generated throughout the update, and on screens, both of which can be easily translated by the developer for multi-lingual updates.

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 ...\TrueUpdate 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 update. 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 update. 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 update:

A list of all of the languages that are currently supported in the project.

Language

The names of the languages currently added to the update.

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 update will use this language for its messages and screens.

Note: There can only be one default language per update.

Language File

The full paths to the XML language message files. You will find the available language files in the "Languages" subfolder of the main TrueUpdate 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 update.

Remove

Removes the currently selected language from your update.

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

Set Default

Set the currently selected language to be "Default" language. This means that if the detected language is not supported by your update, 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.


Preferences - Overview

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

The Preferences dialog is where you can find the settings and options that let you configure the TrueUpdate design environment to your liking.

To access the Preferences dialog, choose Edit > Preferences... from the program menu.

There are 10 categories on the Preferences dialog:

  • Build

  • Code Signing

  • Document

  • Languages

  • Environment

  • Folders

  • Script Editor

  • Spell Checker

  • Startup

  • Updates


Build Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

You can use these settings to control how TrueUpdate builds a project. To view and change any build options, use the Build Settings dialog (Publish > Settings...).

Build with Publish Wizard

If selected, TrueUpdate will use the Publish Wizard when building. If not selected, TrueUpdate will build using the settings specified in Build Settings.

Open output folder after build

Make TrueUpdate open the output folder by default after a build has completed.

Show publish report after build

Make TrueUpdate open an HTML document summarizing what was done during the build and publish process and where to find the generated files.

Confirm before building (non-Wizard mode only)

If selected, TrueUpdate will confirm the build process before continuing. If unselected, TrueUpdate will build the project as soon as build is selected.

Note: This setting has no effect when the Publish Wizard is used.

Exclude fonts from build:

The font face names that will not be included in the build if you choose to override the default fonts in a theme or on a page. By default this field includes Arial, Courier New, and Times New Roman. This saves you from the space taken up by say Arial when all you did was change the font size.


Code Signing Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Code Signing Defaults

These settings are the default values that will be used on the Code Signing tab of the Build Settings dialog when new projects are started.

CodeSign updates

Code sign all new updates during the build process.

Code signing tool:

The tool you want to use to digitally sign all new project updates. Choose from:

SignTool.exe

Use SignTool.exe to digitally sign the client update 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 client update 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 updates. If SignTool.exe is selected, this file must be a "Personal Information Exchange" file (*.PFX). If SignCode.exe is selected, this file must be a "Software Publisher Certificate" file (*.SPC). You can click the Browse button to select the file.

Tip: If your .PFX file is password protected, you must pass its value in the Other arguments field using the /p option. For example: /p "mypassword". For more information, see MSDN: SignTool (Windows).

Private key filename:

The full path and filename of the "Private Key" file (*.pvk) to use for signing all new project updates. 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 updates, such as: http://timestamp.verisign.com/scripts/timstamp.dll. If you do not want to timestamp the client 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. TrueUpdate automatically passes the "sign" argument when "SignTool.exe" is the selected tool.


Document Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Auto-Save

Enabled

Make TrueUpdate save your project automatically at regular intervals.

Interval:

The time in minutes to wait between autosaves. This is how long TrueUpdate 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 TrueUpdate 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.sf7

Undo/Redo

Levels

The maximum number of changes that will be undo-able in TrueUpdate. (Set this to 0 to disable the undo/redo feature.)

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.


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 names of the languages that will automatically be added to new projects.

Default

Whether the selected language will be the default language for new projects created.

Add

Opens the Add New Language dialog where you can add a new default language to your project.

Remove

Removes the selected language.

Set Default

Sets the selected language as the default language.


Environment Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Themes

GUI

The default style to use for the Graphical User Interface.

Docking pane

The default style to use for the docking panes.

Note: The default folders used by TrueUpdate are specified in the Folder Preferences dialog.


Folder Preferences

Preferences

Environment Folders

Temporary build files:

The full path to the folder where TrueUpdate 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 TrueUpdate will save the client files and server files generated during the build process. Click the browse button ( [image] ) to select a new folder.

Preference files:

The full path to the location where TrueUpdate will store its preferences files. Click the browse button ( [image] ) to select a new folder.

Project files:

The full path to the default location where TrueUpdate will store any project files which are saved. Click the browse button ( [image] ) to select a new folder.

Additional themes:

A semi-colin delimited list of folder paths that you want TrueUpdate to parse looking for additional project themes beyond the ones in the Themes folder of the program. For example, C:\MyProjectThemes;Z:\TUThemes. This allows you to store themes on a network drive that can be shared between products and developers.

If TrueUpdate encounters a theme with a name that already exists when reading in the available themes, it will use the last read theme. For example, if a custom theme in a different directory has the same name as a theme located in the product themes folder, the custom theme will override the one in the themes folder.

To store a theme in a different location, first save it to the program's Themes folder and then copy the created theme folder to an external location.


Script Editor Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Double-click opens action's properties dialog

Controls whether or not the action's properties dialog will open when you double-click an action in the script editor window. If unchecked, double-clicking any text in the script editor simply selects the text, as in most other text editors.

Automatic syntax checking

Controls whether or not a check is performed on scripts to make sure they are syntactically correct. It does not check for logical or other programming errors, simply syntax. This check is performed when leaving the current script editor window. If unchecked, no syntax checking is performed.

Confirm cancel when scripts are modified

Controls whether or not a confirmation dialog will appear after you click the Cancel button in the action editor when there are unsaved changes. If unchecked, cancelling will exit the dialog without notice and you will lose any changes that have been made.

Show controls actions in Action Wizard on main scripts

Controls whether or not the controls actions (DlgCheckBox, DlgStaticText, etc.) will appear in the action wizard when called from the main scripts (Client Script, Server Script, additonal server scripts). If unchecked (default) they can still be used, but will not appear in the action wizard. If checked, the controls will appear in the action wizard. Since these actions can only be used on a screen containing those controls, you would normally only select this option if you plan on writing functions on the main script tabs containing these types of actions.


Spell Checker Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

You can use these settings to control the spell checker features within fields that support spell checking (each field that supports spell checking will enable a Spell Checking... option in the right-click context menu).

Always suggest corrections

Suggest possible corrections for any spelling mistakes encountered.

Suggest from main dictionaries only

Show spelling mistake suggestions from the Main Dictionaries only (not the Custom Dictionary).

Ignore words in UPPERCASE

Ignore any uppercase words in the text. For example, INDIGO ROSE.

Ignore words with numbers

Ignore any words in the text that contain numbers. For example, am4.

Ignore Internet and file addresses

Ignore any internet or file addresses in the text. For example, http://www.indigorose.com, or C:\Program Files\myfile.txt.

Capitalize sentences

Automatically capitalize the first letter of a new sentence.

Custom Dictionary:

The full path to your custom dictionary file. This file can be included or added to when you encounter common words that are not in the main dictionary. You can click the browse button ( [image] ) to select a custom dictionary file (*.dic). Additional dictionaries can be downloaded from TrueUpdate's web site, www.trueupdate.com.

Main Dictionaries:

The full paths to your main dictionary files (*.lex). You can use the New, Delete and Up/Down arrows to manipulate the dictionary file list.


Startup Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

When this Program Starts

Show welcome dialog

Shows the welcome dialog, allowing a choice of creating a new project, opening an existing project, opening the last used project, or exiting TrueUpdate.

Open last project

Automatically opens the last project used when TrueUpdate is launched.

Start new project

Automatically stars a new project when TrueUpdate is launched.


Updates Preferences

Preferences

Overview Build Code Signing Document Environment Script Editor Spell Checker Startup Updates

Auto-Update

Enabled

Whether to automatically check for new versions of the TrueUpdate 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 TrueUpdate.

Frequency

How often (the number of days) you want TrueUpdate to check for an update.

Silent until update available

Only show the TrueUpdate 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 TrueUpdate will use when it checks for updates. These are the same settings that Internet Explorer uses.


Program Menus

Overview File Edit Project Script Publish View Tools Help

Most of the features of TrueUpdate can be accessed from the program menus. By default, the program menus are located at the top of the TrueUpdate program window just under the title bar.

The program menus are organized into eight categories:

  • File

  • Edit

  • Project

  • Script

  • Publish

  • View

  • Tools

  • Help


File Menu

Program Menus

Overview File Edit Project Script Publish View Tools Help

New Project

Opens a new TrueUpdate project. If there are any unsaved changes in the current project, you will be prompted to save them. You can also access this menu item using Ctrl+N.

Open...

Opens a previously saved TrueUpdate project file. TrueUpdate projects have the ".tu2" file extension. You can also access this menu item using Ctrl+O.

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.

Print...

Prints the action script in the currently selected script tab. You can also access this menu item using Ctrl+P.

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 TrueUpdate projects.

Exit

Closes the current project and exits out of TrueUpdate. If there are any unsaved changes in the current project, you will be prompted to save them.


Edit Menu

Program Menus

Overview File Edit Project Script Publish View Tools Help

Undo

Undoes the last command performed in the program. You can also access this menu item using Ctrl+Z.

Redo

Redoes the last Undo command performed in the program. You can also access this menu item using Ctrl+Y.

Cut

Removes the currently selected items from the project and stores them in the Windows clipboard. Once on the clipboard, they can be pasted to another location or another project. You can also access this menu item using Ctrl+X.

Copy

Copies the currently selected items to the Windows clipboard. Once on the clipboard, they can be pasted to another location or another project. You can also access this menu item using Ctrl+C.

Paste

Pastes one or more items from the Windows clipboard to somewhere in your project. You can also access this menu item using Ctrl+V.

Select All

Selects all of the items in the currently selected panel, or script tab. You can also access this menu item using Ctrl+A.

Find...

Opens a Find dialog where you can specify a string of text you would like to search for in the current script tab. You can also access this menu item using Ctrl+F.

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 current script tab and the string you would like to replace it with. You can also access this menu item using Ctrl+H.

Bookmarks

Create and manage bookmarks in the code window so you can easily jump to specific spots in your code.

Toggle Bookmark

Add or remove a bookmark from the current action script line. You can also access this menu item using Ctrl+F2.

Clear All

Remove all bookmarks from the current code window.

First

Jump to the first bookmarked action script line.

Previous

Jump to the previous bookmarked action script line. You can also access this menu item using Shift+F2.

Next

Jump to the next bookmarked action script line. You can also access this menu item using F2.

Last

Jump to the last bookmarked action script line.

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 of the Editor Settings dialog. The Editor Settings dialog can be accessed by selecting Tools > 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.

Record

Start recording a macro that can be played back at a later time. You can click the "End Recording" button on the Record Macro dialog to stop recording. To playback the recorded macro, you can select the Play option found underneath this menu option. You can also access this menu item using Ctrl+Shift+R.

Advanced

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. You can also access this menu item using F12

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.

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

Editor Settings...

Opens the action editor's Editor Settings dialog where you can customize its settings. You can also access this menu item using Ctrl+Enter.

Preferences...

Opens the Preferences dialog where you can customize the TrueUpdate design environment to suit your style.


Project Menu

Program Menus

Overview File Edit Project Script Publish View Tools Help

TrueUpdate Servers...

Opens the Project Settings dialog to the TrueUpdate Servers tab where you can configure the locations you will be hosting the server configuration files.

Session Variables...

Opens the Project Settings dialog to the Session Variables tab where you can define the session variables that will be used in your project.

Theme...

Opens the Project Settings dialog to the Theme tab where you can configure a set of visual attributes that are applied to all of the screens in your update to give them a uniform look and feel.

Options...

Opens the Project Settings dialog to the Options tab where you can configure settings for the update window, log file and taskbar.

Advanced

Opens the Project Settings dialog to the Advanced tab where you can configure settings that control what to do if the client executable or data file needs updating, but the source folder is not writable.

Plugins...

Opens the Resources dialog to the Plugins tab where you can add action plugins to your project.

Includes...

Opens the Resources dialog to the Includes tab where you can include external script files (*.lua) in your project.

Languages...

Opens the Languages dialog where you can define what languages you want to support in your update.


Script Menu

Program Menus

Overview File Edit Project Script Publish View Tools Help

Action Wizard...

Opens the action wizard where you can add new actions to the code window. You can also access this menu item using Ctrl+W.

Edit Action...

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 menu option will open its properties dialog where you can modify its settings. You can also access this menu item using Ctrl+E.

Quick Scripts

A menu containing a variety of code templates you can add to the code window. You can find further information on code structures in the Scripting Guide.

Insert

Variable...

Opens the Insert Variable dialog where you can insert Design-time Constants, built-in Session Variables or Global Variables into your project at the current cursor location. You can also access this menu item using Ctrl+B.

File Path...

Opens a file browse dialog where you can select a file from your system whose full path you want to insert. You can also access this menu item using Ctrl+I.

Folder Path...

Opens a folder browse dialog where you can select a folder from your system whose path you want to insert. You can also access this menu item using Ctrl+D.

New

Add a new custom script tab to your project.

Remove

Remove the currently selected custom script tab from your project.

Note: You can only remove custom scripts. You cannot remove the Client Script or Server Script tabs.

Rename...

Rename the currently selected custom script tab.

Note: You can only rename custom scripts. You cannot rename the Client Script or Server Script tabs.

Duplicate

Makes a duplicate copy of the selected script tab and its contents, and adds it to your project. After the script tab has been duplicated and added to your project, you can rename it using the Rename... option on this menu.

Organize...

Opens the Organize Scripts dialog where you can change the visible order of your custom script tabs in the design environment.

Note: You must have at least two custom script tabs in order to use this feature.


Publish Menu

Program Menus

Overview File Edit Project Script Publish View Tools Help

Build...

Starts the build process for the current project. You can also access this menu item using F7.

Settings...

Opens the Build Settings dialog where you can configure the settings you want to use for the build process. Some of these settings include the output folders, upload locations, design-time constants, and pre/post build options.


View Menu

Program Menus

Overview File Edit Project Script Publish View Tools Help

Toolbars

Shows or hides the available toolbars.

Standard

Shows or hides the standard program toolbar.

Edit

Shows or hides the Edit toolbar.

File

Shows or hides the Files toolbar.

Project

Shows or hides the Project toolbar.

Script

Shows or hides the Script toolbar.

Publish

Shows or hides the Publish toolbar.

View

Shows or hides the View toolbar.

Tools

Shows or hides the Tools toolbar.

Help

Shows or hides the Help toolbar.

Script Help

Shows or hides the Script Help toolbar. This toolbar contains a field that shows the action definition of the action that your cursor is currently located on in the code window.

Customize...

Opens the Customize dialog where you can create custom toolbars, shortcut keys or link to external programs.

Status Bar

Shows or hides the status bar at the bottom of the TrueUpdate main screen.

Client Screens

Shows or hides the Client Screens panel containing all of the client screen lists and screens in your project.

Server Screens

Shows or hides the Server Screens panel containing all of the server screen lists and screens in your project.

Screen Preview

Shows or hides the Screen Preview panel. The Screen Preview panel shows a preview of the currently selected screen in the Screens panel.

Help

Shows or hides the Help panel. The Help panel is a docking panel containing the Command Reference.

Messages

Shows or hides the Messages panel. The messages panel contains information such as the build log or any other project output.

Previous Script

Selects the previous script tab. Script tabs are organized in sequential order starting from left to right, so the script tab on the left of the current script tab will be selected. You can also access this menu item using Shift+F6.

Next Script

Selects the next script tab. Script tabs are organized in sequential order starting from left to right, so the script tab on the right of the current script tab will be selected. You can also access this menu item using F6.


Tools Menu

Program Menus

Overview File Edit Project Script Publish View Tools Help

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

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.

Get File Version...

Opens the Get File Version dialog, where you can get the version of any file on your system. This can be useful if you are comparing file versions during your update.

IRScriptEditor...

Opens the Indigo Rose Script Editor application. This is a stand-alone program allowing you to edit action scripts outside of TrueUpdate with support for syntax highlighting, intellisense code completion and help file integration. This application is named "IRScriptEditor.exe" and can be found in the TrueUpdate program folder.

Editor Settings...

Opens the action editor's Editor Settings dialog where you can customize its settings. You can also access this menu item using Ctrl+Enter.

Customize...

Opens the Customize dialog where you can create custom toolbars, themes, shortcut keys or link to external programs.


Help Menu

Program Menus

Overview File Edit Project Script Publish View Tools Help

TrueUpdate Help

Opens the online help for TrueUpdate.

TrueUpdate User's Guide

Opens the .PDF format user's guide for TrueUpdate.

What's New?

Opens the What's New in TrueUpdate topic in the online help. There you will find what new features have been added to TrueUpdate.

Ordering Information

Opens the "Ordering Information" topic in the online help where you can find ordering information for TrueUpdate.

Buy Online

Opens your web browser to a web page where you can order TrueUpdate 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.

Visual Patch

Opens your web browser to the Visual Patch web site. Visual Patch allows you to create full-history patches for your software products.

Home Page

Opens the your web browser to the Indigo Rose 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 TrueUpdate is available.

About TrueUpdate...

Opens the About dialog which shows the copyright and version information for TrueUpdate. Use this whenever you need to find out what version and build of TrueUpdate you currently have.


Project File Properties - Overview

Project File Properties

Overview General Statistics

The project file's properties are mainly used for organizational purposes and can only be accessed from within the design environment on the Project File Properties dialog.

To access the Project File Properties dialog, choose File > Properties... from the program menu.

There are two tabs on the Project File Properties dialog:

  • General

  • Statistics


General

Project File Properties

Overview General Statistics

Note: The following information will not be visible in the project's generated runtime.

Filename:

The full path and filename of your TrueUpdate project file (.tu2).

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 TrueUpdate project file (in bytes).

Created:

The creation date and time of the project file.

Modified:

The date and time of the last modification to the project file.

Accessed:

The date and time the project file was last accessed.

Created Ver:

The full build number the project was created with.

Last Saved Ver:

The full build number the project was last saved with.


Project Settings - Overview

Project Settings

Overview TrueUpdate Servers Session Variables Theme Options Advanced

The Project Settings dialog is where you can configure various update settings for your project. The first section allows you to define where you would like to host your server configuration files. TrueUpdate offers a variety of publishing options for these files such as a local/network drive, HTTP site, HTTPS enabled site or FTP site.

The second category of settings allow you to define a series of built-in and custom session variables for your update. These are used as dynamic placeholders for commonly used values in your update such as your product and company name.

The theme section allows you to configure a set of visual attributes that are applied to all of the screens in your update to give them a uniform look and feel. These attributes include the color, banner styles, images, text fonts and many more.

The options category contains some additional options for your update such as its window settings, taskbar visibility and log file generation.

The last category contains settings for controlling what happens if the client needs to be updated, but the user does not have the appropriate write permissions.

Each of these categories can be accessed from the Project program menu.

The Project Settings dialog contains the following five categories:

  • TrueUpdate Servers

  • Session Variables

  • Theme

  • Options

  • Advanced


TrueUpdate Servers

Project Settings

Overview TrueUpdate Servers Session Variables Theme Options Advanced

The TrueUpdate Servers dialog is where you can configure all of the locations that will be used to host your server configuration files. There are several options for hosting your server configuration files such as on a local/network drive, a Web server, a Web server utilizing HTTPS, or an FTP site. These are the locations that the TrueUpdate client can attempt to download its server configuration files from. The server configuration files are the *.ts1, *.ts2 and *.ts3 files generated during the build.

There are various actions available for getting, loading and running server configuration files at run time, such as TrueUpdate.GetServerFile, TrueUpdate.LoadServerFile and TrueUpdate.RunScript. All applicable actions can be found in the TrueUpdate category of the actions list.

Name

The names of each TrueUpdate server location currently defined in your project.

Location

The locations of each TrueUpdate server, for example, its URL, FTP site or local/network folder.

Tip: TrueUpdate server locations also support the expansion of session variables allowing you to change the locations dynamically at runtime.

Type

The types of each of the TrueUpdate server locations, such as LAN, HTTP, HTTPS and FTP.

Add

Add a new TrueUpdate server location to your project. The following server location types are available:

HTTP Server

The server location is on a Web server such as http://www.indigorose.com/myfiles/. This opens the TrueUpdate Server (HTTP) dialog where you can configure its settings.

HTTPS Server

The server location is on a Web server that utilizes the secure version of HTTP (HTTPS), such as https://www.indigorose.com/myfiles/. This opens the TrueUpdate Server (HTTPS) dialog where you can configure its settings.

FTP Server

The server location is an FTP site. This opens the TrueUpdate Server (FTP) dialog where you can configure its settings.

LAN/Local Server

The server location is a local or network drive. This opens the TrueUpdate Server (LAN/Local) dialog where you can configure its settings.

Remove

Removes the currently selected TrueUpdate server location from your project.

Edit

Opens a settings dialog where you can edit the properties of the currently selected TrueUpdate server location. Some of these properties include its address, ports and user names/passwords.

Up ( )

Move the selected TrueUpdate server location up one position in the server location list.

Down ( )

Move the selected TrueUpdate server location down one position in the server location list.


Session Variables

Project Settings

Overview TrueUpdate Servers Session Variables Theme Options Advanced

The Session Variables tab is where you can set general information and defaults about your product such as your product name and company name. These values are automatically assigned to built-in session variables that you can use throughout your update. You can also create custom session variables that behave in the same manner. Session variables are mainly used to display dynamic values on screens. If you need to create a variable, but do not need to display its contents on a screen, you should use a Lua variable instead.

Note: All session variables defined here are stored in the client's data. If their values change, or new variables are added after the client has been distributed, the client data will require updating. This means that after the server configuration files have been downloaded, the client will restart itself. If you foresee yourself needing to change these values after you distribute your client, you should instead create session variables at runtime using SessionVar.Set actions.

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, "TrueUpdate".

%CompanyName%

The name of your company. For example, "Indigo Rose Software".

%Copyright%

A copyright notice for the product. For example, "Copyright © 2012 - Indigo Rose Software".

Custom

A list of all of the currently defined custom session variables that are available in your update.

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 TrueUpdate Servers Session Variables Theme Options Advanced

Project themes are a set of visual attributes that are applied to all of the screens in your update 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 update. These themes are stored globally and can be used for all of your projects.

Tip: Themes are very much like "skins" for your update. If you'd like to create your own themes, see Screen Dimensions and How Screens Are Drawn for some useful 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.

Edit

Opens the Theme Properties dialog where you can edit the properties of the selected project theme.

Note: You cannot edit the default TrueUpdate 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 TrueUpdate themes.


Options

Project Settings

Overview TrueUpdate Servers Session Variables Theme Options Advanced

Window Settings

Taskbar title:

The text that will appear on the windows task bar while the update is running.

Use custom icon:

Display a custom icon in the top left corner of your update window. It will also be used to represent the update on the Windows task bar. Click the Browse button to select an icon file (*.ico).

Encryption Key

The encryption key to use to encrypt the server configuration files for the project. The client will use this key to decrypt all future server configuration files generated for the project. You can click the Change button to use a different key. We recommend the encryption key be longer than 16 characters in length.

Note: Generally encryption keys should only be changed before you distribute your update for the first time. If you change the encryption key after your client files have been distributed, you must also redistribute the newly created client files for the server files to be decrypted successfully.

Log File

Create log file

Generate an update log file during the update. The update log file is in ASCII text format and provides information about what happened during the update, mainly if errors occur. This information can be extremely useful if you ever need to debug an update where errors occurred. You can also write custom information to the log file at any point using the TrueUpdate.WriteToLogFile action.

Filename:

The location and filename of the log file to generate. You can specify an absolute location such as C:\Temp or you can use session variables to form dynamic paths such as %TempFolder%\logfile.txt.

Note: The log file is created at the very start of the update so 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).

Taskbar Visibility

Taskbar

Display the Taskbar title in the Windows task bar. This is the normal Windows application behavior.

System tray

Display the update's icon in the system tray. The system tray is normally on the right hand side of the Windows task bar.

Hidden

Hide the taskbar icon during the update.

Tip: See the command line option /NOFOCUS to force the client not to steal focus from the currently running application.


Advanced

Project Settings

Overview TrueUpdate Servers Session Variables Theme Options Advanced

An exciting feature of TrueUpdate is the client's ability to update itself if a newer version becomes available. There are two parts in the client that may be updated: the client executable and the client data file. They are both part of the server configuration files that are updated each time a build is done. While TrueUpdate is able to update these files, they may exist in a location where the end user does not have write access. These settings allow you to configure how TrueUpdate should proceed if faced with this situation.

Tip: If the client executable or client data file is updated, the update process must be restarted. You can use the global variable _ClientRestarted to tell whether or not the client was restarted.

Client Executable

What should TrueUpdate do if a newer version of the client executable exists, but the folder is not writable. Choose from:

Notify user and abort

Notify the user that they do not have the appropriate permissions to update the client by showing and dialog and aborting the update process.

Ignore and continue

Ignore the new version of the client executable and continue by running the current copy.

Download to a temporary writable location

Download the new version of the client executable to a temporary location (Windows Temp folder) and run it from there.

Note: Choosing this option may cause your update to function incorrectly if you are referencing files from your update that rely on the client's location such as _SourceFolder or %SourceFolder%.

Client Data File

What should TrueUpdate do if a newer version of the client data file exists, but the folder is not writable. Choose from:

Notify user and abort

Notify the user that they do not have the appropriate permissions to update the client by showing and dialog and aborting the update process.

Ignore and continue

Ignore the new version of the client data file and continue by running the current copy.

Download to a temporary writable location

Download the new version of the client data file to a temporary location (Windows Temp folder) and run it from there.

Requested User Privilege Level

This section specifies which requested execution level to include in the client update executable's application manifest for distribution on Windows Vista, Windows 7 and Windows 8. Updates should generally always be built using the default "Require administrator" setting. Before changing this default setting, see Updates On Windows Vista for important information concerning required changes to your update, and feature limitations.

Important Note: It is very important to make the correct decision when initially distributing your TrueUpdate client. Changing the manifest setting of the client in an update may cause it to fail. If an existing client was published using the As invoker setting, and you published again changing it to Require administrator, the automatic update of the client will fail to run the new update client.

Note: Changing the application manifest to "Highest available" or "As invoker" is only supported on Windows 2000 or later in TrueUpdate's design environment.

Note: For more information on the settings below and general Windows Vista/Windows 7/Windows 8 information, see Updates On Windows Vista.

As invoker

The update 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 update. 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 update 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 update requires to be run with the full access token of an administrator. Generally updates make changes to protected system locations that are typically writable to only by administrator users. This is the default setting for updates created with TrueUpdate.


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, configure your download and upload settings, choose a theme for your update, select various languages, and configure a handful of other features. The project wizard can be used to create a simple, fully functioning update, 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 from the Document page of the Preferences. The Preferences dialog can be found by choosing Edit > Preferences... from the program menu.


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

  • Interface Type

  • Theme

  • Multilingual Settings

  • Download Method

  • TrueUpdate Server Download Settings - HTTP

  • TrueUpdate Server Download Settings - HTTPS

  • TrueUpdate Server Download Settings - FTP

  • TrueUpdate Server Download Settings - LAN

  • Server Files Prefix

  • Upload Method

  • TrueUpdate Server Upload Settings - FTP

  • TrueUpdate Server Upload Settings - SFTP

  • TrueUpdate Server Upload Settings - File Copy

  • Version Identification

  • Registry Value

  • File Information

  • INI File Value

  • Target Version

  • Update Method

  • Custom Update Method

  • Installer/Patch Download Method

  • Installer/Patch Download Settings - HTTP

  • Installer/Patch Download Settings - HTTPS

  • Installer/Patch Download Settings - FTP

  • Installer/Patch Download Settings - LAN

  • Installer/Patch File Settings

  • Ready to Create New Project


General Information

Project Wizard

Contents General Information

The General Information page is the first page of the Project Wizard that allows you to configure your company information, as well as the encryption key that will be used to encrypt the server configuration files that will be made available on your server or network.

TrueUpdate Project Wizard

What is your company name?

Your company name, for example Indigo Rose Software. This value will be stored in the built-in session variable %CompanyName%.

What is your product's name or title?

Your product's name, for example TrueUpdate. This value will be stored in the built-in session variable %ProductName%.

Please specify a unique (per-project) server file encryption key:

The encryption key you want to use to encrypt the server configuration files for this project. Each time the project wizard is started, TrueUpdate will automatically generate an encryption key for you, but you can change it if you wish. We recommend the encryption key be longer than 16 characters in length. This setting can be found on the Options tab of the Project Settings dialog, which can be found by choosing Project > Options... from the program menu.

Next

Proceed to the next project wizard page, Interface Type.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Project Wizard

Contents Interface Type

TrueUpdate has the flexibility to use one of several different types of interfaces for the update. Whether you prefer a full wizard screen, a minimalist dialog approach, or a silent update with no visual interface at all, TrueUpdate can handle each situation with ease.

Interface Type

Wizard style

Use a full wizard style interface for the update. A wizard style interface consists of TrueUpdate screens.

Dialog style

Use dialogs for the interface of the update.

Silent

Don't show any user interface while the update is running.

Don't show any interface unless an update is available

Only show an interface if an update is available.

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:

Theme
Multilingual Settings

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Theme

Project Wizard

Contents Theme

TrueUpdate 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 changed later on the Theme tab of the Project Settings dialog. You can access this dialog by choosing Project > Theme... from the program menu.

Select a project theme:

The project theme that your update will use.

Note: The project theme selected will be used by default on all screens. To customize the look and feel of any individual screen in your project, edit the screen style from the screen's properties dialog.

Back

Go back to the General Information page.

Next

Proceed to the next project wizard page, Multilingual Settings.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Multilingual Settings

Project Wizard

Contents Multilingual Settings

TrueUpdate supports the use of multiple languages in your update. This project wizard page allows you to select the languages you would like to support in your update. If you need to add languages later, you can add them on the Languages dialog, found by choosing Project > Languages... from the program menu.

What languages do you want your update to support?

The languages that will be supported by your update. Check the boxes beside each language you would like to support.

Note: Not all languages contain pre-made message files and translated screens. Languages that are currently installed will show a "*" character beside its name. Most language modules are installed with TrueUpdate, but any additional language modules that are available can be downloaded from TrueUpdate's web site, www.trueupdate.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.

Which language should be used by default?

The language that your update will use by default. If the user's detected language is not present in the supported language list, the update will use this language for its messages and screens.

Back

Go back to the Theme page.

Next

Proceed to the next project wizard page, Download Method.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Project Wizard

Contents Download Method

TrueUpdate contains several different download options that can be used by the TrueUpdate client to download the server configuration files. The option you should choose depends on where you plan to host the server configuration files generated by TrueUpdate. You can host them on a Web server, FTP site, or a local area network (LAN). These settings can be found on the TrueUpdate Servers tab of the Project Settings dialog. You can access that tab by choosing Project > TrueUpdate Servers... from the program menu.

Note: If while running your update, you receive error 3624 and you have already confirmed that all of the server configuration files have been properly uploaded, make sure that the *.ts* extensions are part of the MIME types list on the server.

Download Method

HTTP

You will be hosting the server configuration files on a Web server.

HTTPS

You will be hosting the server configuration files on Web server that utilizes the secure version of HTTP, HTTPS.

FTP

You will be hosting the server configuration files on an FTP site.

LAN

You will be hosting the server configuration files on a local area network (LAN) or local drive.

Back

Go back to the Multilingual Settings page.

Next

The next project wizard page is based on the download method selected. It will be one of the following pages:

TrueUpdate Server Download Settings - HTTP
TrueUpdate Server Download Settings - HTTPS
TrueUpdate Server Download Settings - FTP
TrueUpdate Server Download Settings - LAN

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


TrueUpdate Server Download Settings - HTTP

Project Wizard

Contents TrueUpdate Server Download Settings - HTTP

This project wizard page contains the settings that are required to download the server configuration files from your Web server. If you need to adjust these settings later, they can be found on the TrueUpdate Servers tab of the Project Settings dialog, found by choosing Project > TrueUpdate Servers... from the program menu.

TrueUpdate Server (HTTP)

Folder URL:

The URL containing the directory where the server configuration files will be hosted (e.g. "www.yourdomain.com/trueupdate/").

Note: The protocol designator is optional, e.g. "www.yourdomain.com/trueupdate/" and "http://www.yourdomain.com/trueupdate/" are equally valid.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate client and this HTTP site.

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:

The port to connect to on the HTTP server. The standard HTTP port 80 is used by default.

Authentication

This section allows you to specify a user name and password if the URL is protected by basic HTTP authentication.

Use authentication:

Include basic HTTP authentication information in the HTTP request.

Username:

The user name to use during authentication.

Password:

The password to use during authentication.

Back

Go back to the Download Method page.

Next

Proceed to the next project wizard page, Server Files Prefix.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


TrueUpdate Server Download Settings - HTTPS

Project Wizard

Contents TrueUpdate Server Download Settings - HTTPS

This project wizard page contains the settings that are required to download the server configuration files from your secure Web server using HTTPS. If you need to adjust these settings later, they can be found on the TrueUpdate Servers tab of the Project Settings dialog, found by choosing Project > TrueUpdate Servers... from the program menu.

TrueUpdate Server (HTTPS)

Folder URL:

The URL containing the directory where the server configuration files will be hosted on the secure Web server (e.g. "www.yourdomain.com/trueupdate/").

Note: The protocol designator is optional, e.g. "www.yourdomain.com/trueupdate/" and "https://www.yourdomain.com/trueupdate/" are equally valid.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate client and this HTTPS site.

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:

The port to connect to on the HTTPS enabled server. The standard HTTPS port 443 is used by default.

Authentication

This section allows you to specify a user name and password if the URL is protected by basic HTTP authentication.

Use authentication:

Include basic HTTP authentication information in the HTTP request.

Username:

The user name to use during authentication.

Password:

The password to use during authentication.

Back

Go back to the Download Method page.

Next

Proceed to the next project wizard page, Server Files Prefix.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


TrueUpdate Server Download Settings - FTP

Project Wizard

Contents TrueUpdate Server Download Settings - FTP

This project wizard page contains the settings that are required to download the server configuration files from the FTP site. If you need to adjust these settings later, they can be found on the TrueUpdate Servers tab of the Project Settings dialog, found by choosing Project > TrueUpdate Servers... from the program menu.

TrueUpdate Server (FTP)

Folder address:

The full address of the FTP site including the directory where the server configuration files will be hosted (e.g. "ftp.yourdomain.com/trueupdate/").

Note: The protocol designator is optional, e.g. "ftp.yourdomain.com/trueupdate/" and "ftp://ftp.yourdomain.com/trueupdate/" are equally valid.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate client and the FTP site.

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:

The port to connect to on the FTP server. The standard FTP port 21 is used by default.

Authentication

Username:

The name to use to log into the FTP site. Enter "anonymous" or leave blank for anonymous FTP.

Password:

The password for the FTP site that goes with the FTP username. For anonymous FTP, use your email address.

Account:

An FTP account name for servers that require it. (Some servers require a login name, password, and account name instead of just a login name and password.) VERY RARELY necessary.

Use passive mode

Use passive/firewall mode when transferring files. Passive mode (also known as "firewall mode") is required whenever you need to transfer files to or from an FTP server from behind a firewall.

Normally, your computer makes a connection to an FTP server, and the FTP server responds by opening a connection back to your computer. This return connection won't work if your computer can't be reached directly from the Internet. In passive mode, both connections are made from your computer, so the FTP server doesn't have to do any connecting—it just waits passively for your computer to make both of the connections to it.

Most servers support passive mode connections, so it's generally best to leave this setting enabled.

Back

Go back to the Download Method page.

Next

Proceed to the next project wizard page, Server Files Prefix.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


TrueUpdate Server Download Settings - LAN

Project Wizard

Contents TrueUpdate Server Download Settings - LAN

This project wizard page contains the settings that are required to retrieve the server configuration files from your local area network (LAN). If you need to adjust these settings later, they can be found on the TrueUpdate Servers tab of the Project Settings dialog, found by choosing Project > TrueUpdate Servers... from the program menu.

TrueUpdate Server (LAN)

Folder path:

The path to the folder where the server configuration files will be hosted. This can be a full or UNC path to a mapped drive. You can click the Browse button to select a folder from your system.

Back

Go back to the Download Method page.

Next

Proceed to the next project wizard page, Server Files Prefix.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Project Wizard

Contents Server Files Prefix

When an update is created through TrueUpdate, there are three server configuration files that are generated, *.ts1, *.ts2 and *.ts3. This page allows you configure the name that will be given to these three server files. If you need to change this setting later, it can be found on the Output tab of the Build Settings dialog, which can be accessed by choosing Publish > Settings... from the program menu.

Server Files Prefix

Server files prefix:

The prefix that will be used for all of the server configuration files that are generated during the build process. For example, if the name is myproduct, the files generated will be myproduct.ts1, myproduct.ts2 and myproduct.ts3. The recommended format is all lowercase alphabetic characters containing no spaces.

Back

Go to the previous project wizard page.

Next

Proceed to the next project wizard page, Upload Method.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Project Wizard

Contents Upload Method

TrueUpdate contains several different upload options that can be used to publish the generated files. The option you should choose depends on where you decided to host the server configuration files on the Download Method page of the project wizard. You can publish your server configuration files using FTP, SFTP, or by copying the file, or you can bypass this decision all together. If you want to change these settings later, they can be found on the Upload tab of the Build Settings dialog. You can access that dialog by choosing Publish > Settings... from the program menu.

Upload Method

I will do this myself manually or will configure it later

Don't worry about the upload settings now. I will handle the uploading myself or configure it when I'm ready to publish my project.

FTP

Upload the server configuration files using FTP when publishing.

SFTP

Upload the server configuration files using SFTP when publishing. SFTP transfers data securely over SSH layer using AES, DES, and BLOWFISH encryption.

File copy

Copy the server configuration files to a local or network folder when publishing.

Back

Go back to the Server Files Prefix page.

Next

The next project wizard page is based on the upload method selected. It will be one of the following pages:

Version Identification
TrueUpdate Server Upload Settings - FTP
TrueUpdate Server Upload Settings - SFTP
TrueUpdate Server Upload Settings - File Copy

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


TrueUpdate Server Upload Settings - FTP

Project Wizard

Contents TrueUpdate Server Upload Settings - FTP

This project wizard page contains the settings that are required to upload the server configuration files using FTP. If you need to adjust these settings later, they can be found on the Upload tab of the Build Settings dialog, found by choosing Publish > Settings... from the program menu.

Upload Settings (FTP)

Folder address:

The full address of the FTP site including the directory (e.g. "ftp.yourdomain.com/trueupdate/") that you want to upload the server configuration files to when publishing.

Note: The protocol designator is optional, e.g. "ftp.yourdomain.com/trueupdate/" and "ftp://ftp.yourdomain.com/trueupdate/" are equally valid.

Test

Test the FTP settings to ensure they are correct by uploading a small file and then deleting it. A dialog will open to show the status and result of the test.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate publisher and the FTP site.

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:

The port to connect to on the FTP server. The standard FTP port 21 is used by default.

Authentication

Username:

The name to use to log into the FTP site. Enter "anonymous" or leave blank for anonymous FTP.

Password:

The password for the FTP site that goes with the FTP user name. For anonymous FTP, use your email address.

Account:

An FTP account name for servers that require it. (Some servers require a login name, password, and account name instead of just a login name and password.) VERY RARELY necessary.

Use passive mode

Use passive/firewall mode when publishing the server files. Passive mode (also known as "firewall mode") is required whenever you need to transfer files to or from an FTP server from behind a firewall.

Normally, your computer makes a connection to an FTP server, and the FTP server responds by opening a connection back to your computer. This return connection won't work if your computer can't be reached directly from the Internet. In passive mode, both connections are made from your computer, so the FTP server doesn't have to do any connecting—it just waits passively for your computer to make both of the connections to it.

Most servers support passive mode connections, so it's generally best to leave this setting enabled.

Back

Go back to the Upload Method page.

Next

Proceed to the next project wizard page, Version Identification.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


TrueUpdate Server Upload Settings - SFTP

Project Wizard

Contents TrueUpdate Server Upload Settings - SFTP

This project wizard page contains the settings that are required to upload the server configuration files using SFTP. SFTP transfers data securely over SSH layer using AES, DES, and BLOWFISH encryption. If you need to adjust these settings later, they can be found on the Upload tab of the Build Settings dialog, found by choosing Publish > Settings... from the program menu.

Upload Settings (SFTP)

Folder address:

The full address of the FTP site including the directory (e.g. "ftp.yourdomain.com/trueupdate/") that you want to upload the server configuration files to when publishing.

Note: The protocol designator is optiona, e.g. "ftp.yourdomain.com/trueupdate/" and "ftp://ftp.yourdomain.com/trueupdate/" are equally valid.

Test

Test the SFTP settings to ensure they are correct by uploading a small file and then deleting it. A dialog will open to show the status and result of the test.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate publisher and the FTP site.

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:

The port to connect to on the FTP server. The standard SFTP port 22 is used by default.

Authentication

Username:

The name to use to log into the FTP site. Enter "anonymous" or leave blank for anonymous FTP.

Password:

The password for the FTP site that goes with the FTP user name. For anonymous FTP, use your email address.

Account:

An FTP account name for servers that require it. (Some servers require a login name, password, and account name instead of just a login name and password.) VERY RARELY necessary.

Use passive mode

Use passive/firewall mode when publishing the server files. Passive mode (also known as "firewall mode") is required whenever you need to transfer files to or from an FTP server from behind a firewall.

Normally, your computer makes a connection to an FTP server, and the FTP server responds by opening a connection back to your computer. This return connection won't work if your computer can't be reached directly from the Internet. In passive mode, both connections are made from your computer, so the FTP server doesn't have to do any connecting—it just waits passively for your computer to make both of the connections to it.

Most servers support passive mode connections, so it's generally best to leave this setting enabled.

Back

Go back to the Upload Method page.

Next

Proceed to the next project wizard page, Version Identification.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


TrueUpdate Server Upload Settings - File Copy

Project Wizard

Contents TrueUpdate Server Upload Settings - File Copy

This project wizard page contains the settings that are required to copy the server configuration files to a local or network location. If you need to adjust these settings later, they can be found on the Upload tab of the Build Settings dialog, found by choosing Publish > Settings... from the program menu.

Upload Settings (File Copy)

Copy to this folder:

The path to the folder where you want the server configuration files copied to when publishing. This path can be on a local hard drive, or LAN. You can click the Browse button to select a folder on your system.

Back

Go back to the Upload Method page.

Next

Proceed to the next project wizard page, Version Identification.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Version Identification

Project Wizard

Contents Version Identification

In order for TrueUpdate to know whether or not an update needs to take place, the user's system must be queried for some piece of information that will answer this question. This project wizard page contains several version identification methods that can be used to determine whether or not an update is available and needs to run.

Version Identification Method

Registry key

Use a value in the Registry to identify the installed version of the application on the user's system.

File Information

Use file information to identify the installed version of the application on the user's system.

INI file

Use a value in an INI file to identify the installed version of the application that is installed on the user's system.

Other (skip this step for now)

Skip this step for now. You will configure your own identification method while creating your update.

Back

Go to the previous project wizard page.

Next

The next project wizard page is based on the version identification method selected. It will be one of the following pages:

Registry Value
File Information
INI File Value
Update Method

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Registry Value

Project Wizard

Contents Registry Value

This project wizard page contains the Registry location that will be read on the user's system to identify the version of the installed application. This information will be used to determine whether or not an update is available and needs to be run.

Identify Version From Registry

Main key:

The main or "root" key containing the Sub key.

Sub key:

The sub key containing the Value.

Value:

The value whose data will contain the version identifier information.

Value type:

The type of value that will be read from the Registry and used in a comparison. Choose from:

Version

Compare a version number such as 1.0.0.1.

ISO Date

Compare a file date in ISO format such as 2005-06-18T15:11:44.

CRC Value

Compare a CRC value such as 628216324.

Back

Go back to the Version Identification page.

Next

Proceed to the next project wizard page, Target 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 a blank project will be created.


File Information

Project Wizard

Contents File Information

This project wizard page contains the location of the file whose file information will be read on the user's system to identify the version of the installed application. This information will be used to determine whether or not an update is available and needs to be run.

Identify Version From File Info

File:

The full path to the file on the user's system whose file information will be read. By default, this field contains the session variable %SourceFolder% in its path. %SourceFolder% is a variable that expands to the folder where the client executable is located at runtime.

Note: This file must contain version resources such as an executable (*.exe), dynamic link library (*.dll) if you want to read a file or product version.

Information:

The type of information you want to read from the file to use in the comparison. Choose from:

File Version

Read the file version, such as 1.0.0.1.

Product Version

Read the product version, such as 1.0.0.1.

Creation Date

Read the creation date in ISO format, such as 2005-05-26T16:57:52.

Modified Date

Read the modified date in ISO format, such as 2005-06-18T14:55:05.

CRC Value

Calculate the CRC value of the file, such as 628216324.

Back

Go back to the Version Identification page.

Next

Proceed to the next project wizard page, Target 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 a blank project will be created.


INI File Value

Project Wizard

Contents INI File Value

This project wizard page contains the location of the INI file that will be read on the user's system to identify the version of the installed application. This information will be used to determine whether or not an update is available and needs to be run.

Identify Version From INI File

INI file:

The full path to the INI file on the user's system whose version information will be read. By default, this field contains the session variable %SourceFolder% in its path. %SourceFolder% is a variable that expands to the folder where the client executable is located.

Section:

The section in the INI file containing the "value" you want to read.

Value:

The "value" whose data you want.

Value type:

The type of value you want to compare. Choose from:

Version

Compare a version number such as 1.0.0.1.

ISO Date

Compare a file date in ISO format such as 2005-06-18T15:11:44.

CRC Value

Compare a CRC value such as 628216324.

Back

Go back to the Version Identification page.

Next

Proceed to the next project wizard page, Target 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 a blank project will be created.


Project Wizard

Contents Target Version

In order for TrueUpdate to determine whether an update is needed, the information read on the user's system must be compared to some value. This project wizard page allows you to configure the target value of your application. This information will be compared to the value read from the user's system. Generally this is the value you want the installed version updated to.

Target Version

Target value:

The target value of your application. This is the value that you want the installed value compared and updated to. The value you enter here depends upon what type of comparison was selected on the previous project wizard page.

Note: You will also see either a Get File Version, Get File Date or Get File CRC button that can help you choose your target value.

Back

Go to the previous project wizard page.

Next

Proceed to the next project wizard page, Update Method.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Project Wizard

Contents Update Method

Once TrueUpdate has determined that an update is required from the version detection phase, there needs to be a way to get the installed version of the application updated to the target version. This project wizard page provides a couple methods for updating the application. The most common method is by running an installer or patch file. For other available options, you can choose the custom method.

Update Method

Single installer/patch file

Make the client download and run a single install or patch executable to update the application.

Custom

Choose from a list of custom update templates.

Back

Go to the previous project wizard page.

Next

The next project wizard page is based on the update method selected. It will be one of the following pages:

Installer/Patch Download Method
Custom Update Method

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Custom Update Method

Project Wizard

Contents Custom Update Method

While running an installer/patch file is the most common update method, you may find that your update needs don't quite fit into that category. This project wizard page contains templates for other common update scenarios.

Select a custom update method from the following templates:

A list of templates for other common update scenarios that you can choose from. When you highlight a template, a description will be shown in the Description area of the page.

Description:

A brief description of the currently selected update template.

Back

Go back to the Update Method page.

Next

Proceed to the next project wizard page, Ready to Create 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 a blank project will be created.


Installer-Patch Download Method

Project Wizard

Contents Installer/Patch Download Method

TrueUpdate contains several different download options that can be used by the TrueUpdate client to download the installer/patch file. The option you should choose depends on where you plan to host the file. You can host the installer/patch file on a Web server, FTP site, or a local area network (LAN).

Download Method

HTTP

You will be hosting the installer/patch file on a Web server.

HTTPS

You will be hosting the installer/patch file on Web server that utilizes the secure version of HTTP, HTTPS.

FTP

You will be hosting the installer/patch file on an FTP site.

LAN

You will be hosting the installer/patch file on a local area network (LAN) or local drive.

Back

Go back to the Update Method page.

Next

The next project wizard page is based on the upload method selected. It will be one of the following pages:

Installer/Patch Download Settings - HTTP
Installer/Patch Download Settings - HTTPS
Installer/Patch Download Settings - FTP
Installer/Patch Download Settings - LAN

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Installer-Patch Download Settings - HTTP

Project Wizard

Contents Installer/Patch Download Settings - HTTP

This project wizard page contains the settings that are required to download the installer/patch file from your Web server.

Single Installer/Patch File (HTTP)

URL:

The full URL where the installer/patch file will be hosted (e.g. "www.yourdomain.com/patches/patch.exe").

Note: The protocol designator is optional, e.g. "www.yourdomain.com/patches/patch.exe" and "http://www.yourdomain.com/patches/patch.exe" are equally valid.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate client and this HTTP site.

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:

The port to connect to on the HTTP server. The standard HTTP port 80 is used by default.

Authentication

This section allows you to specify a user name and password if the URL is protected by basic HTTP authentication.

Use authentication:

Include basic HTTP authentication information in the HTTP request.

Username:

The user name to use during authentication.

Password:

The password to use during authentication.

Back

Go back to the Installer/Patch Download Method page.

Next

Proceed to the next project wizard page, Installer/Patch File Settings.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Installer-Patch Download Settings - HTTPS

Project Wizard

Contents Installer/Patch Download Settings - HTTPS

This project wizard page contains the settings that are required to download the installer/patch file from your secure Web server using HTTPS.

Single Installer/Patch File (HTTPS)

URL:

The full URL where the installer/patch file will be hosted (e.g. "www.yourdomain.com/patches/patch.exe").

Note: The protocol designator is optional, e.g. "www.yourdomain.com/patches/patch.exe" and "https://www.yourdomain.com/patches/patch.exe" are equally valid.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate client and this HTTP site.

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:

The port to connect to on the HTTPS enabled server. The standard HTTPS port 443 is used by default.

Authentication

This section allows you to specify a user name and password if the URL is protected by basic HTTP authentication.

Use authentication:

Include basic HTTP authentication information in the HTTP request.

Username:

The user name to use during authentication.

Password:

The password to use during authentication.

Back

Go back to the Installer/Patch Download Method page.

Next

Proceed to the next project wizard page, Installer/Patch File Settings.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Installer-Patch Download Settings - FTP

Project Wizard

Contents Installer/Patch Download Settings - FTP

This project wizard page contains the settings that are required to download the installer/patch file from your FTP site.

Single Installer/Patch File (FTP)

Folder address:

The full address of the FTP site including the filename of the installer/patch file that will be hosted (e.g. "ftp.yourdomain.com/patches/patch.exe").

Note: The protocol designator is optional, e.g. "ftp.yourdomain.com/patches/patch.exe" and "ftp://ftp.yourdomain.com/patches/patch.exe" are equally valid.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate client and the FTP site.

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:

The port to connect to on the FTP server. The standard FTP port 21 is used by default.

Authentication

Username:

The name to use to log into the FTP site. Enter "anonymous" or leave blank for anonymous FTP.

Password:

The password for the FTP site that goes with the FTP username. For anonymous FTP, use your email address.

Account:

An FTP account name for servers that require it. (Some servers require a login name, password, and account name instead of just a login name and password.) VERY RARELY necessary.

Use passive mode

Use passive/firewall mode when transferring files. Passive mode (also known as "firewall mode") is required whenever you need to transfer files to or from an FTP server from behind a firewall.

Normally, your computer makes a connection to an FTP server, and the FTP server responds by opening a connection back to your computer. This return connection won't work if your computer can't be reached directly from the Internet. In passive mode, both connections are made from your computer, so the FTP server doesn't have to do any connecting—it just waits passively for your computer to make both of the connections to it.

Most servers support passive mode connections, so it's generally best to leave this setting enabled.

Back

Go back to the Installer/Patch Download Method page.

Next

Proceed to the next project wizard page, Installer/Patch File Settings.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Installer-Patch Download Settings - LAN

Project Wizard

Contents Installer/Patch Download Settings - LAN

This project wizard page contains the settings that are required to retrieve the installer/patch file from your local area network (LAN).

Single Installer/Patch File (LAN)

Installer/patch file:

The complete folder or UNC path and filename of the installer/patch file on your local hard drive or LAN. You can click the Browse button to select a file from your system.

Back

Go back to the Installer/Patch Download Method page.

Next

Proceed to the next project wizard page, Installer/Patch File Settings.

Cancel

Exit the project wizard. Exiting the project wizard means that all information that has been entered in the wizard will be lost and a blank project will be created.


Installer-Patch File Settings

Project Wizard

Contents Installer/Patch File Settings

This project wizard page contains the settings that are used to run the downloaded installer/patch file, such as its download destination and any command line arguments that you would like passed to it.

Single Installer/Patch File

Download installer/patch file to:

The path to the folder you want the installer/patch file downloaded to. By default, this field contains the session variable %SourceFolder% in its path. %SourceFolder% is a variable that expands to the folder where the client executable is located at runtime.

Run Settings

Command line arguments:

The command line arguments to pass to the installer/patch file.

Wait for return

Whether the TrueUpdate client will wait until the installer/patch file has exited before continuing. If checked, the client will wait. If unchecked, the client will proceed after running the file.

Process return code indicates success:

The return code you want to use to indicate that the installer/patch file was successful.

Note: This Wait for return option must be selected if you want to receive a process return code.

Back

Go to the previous project wizard page.

Next

Proceed to the next project wizard page, Ready to Create 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 a blank project will be created.


Ready to Create New Project

Project Wizard

Contents Ready to Create New Project

This is the final project wizard page you see before your new project is created. It contains a summary of all of the settings you configured on previous pages, and is the last chance to go back to previous wizard pages before your project is created.

Summary

Here is a summary of the choices you made:

A detailed summary containing all of the choices you made throughout the project wizard that your new project will be created with. If you see any settings that you would like to change, you can click the Back button to go back to the appropriate project wizard page to make changes.

Back

Go 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 a blank project will be created.


Overview

Publish Wizard

Overview Output Upload Finished

The Publish Wizard is a user friendly means of building and publishing your update. It allows you to see or configure the settings that will be used to generate your final update files and even optionally upload the server configuration files for you.

You will encounter the following publish wizard pages when publishing your update.

  • Output

  • Upload

  • Finished


Output

Publish Wizard

Overview Output Upload 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.

Note: Any changes you make on this page will be saved in the project's build settings.

Output Settings

Output folder:

The directory that you want the TrueUpdate client and server configuration files saved to when it is finished building. You can click the Browse button to select an output folder. There are five files in total that will be saved to this folder, *.exe, *.dat, *.ts1, *.ts2 and *.ts3.

TrueUpdate Client filename:

The name you want to give your TrueUpdate client executable file. This can be update.exe, myupdate.exe or anything else that you want. The data file will also use this file name when it is generated. For example, if your filename was myupdate.exe, the data file would be named myupdate.dat.

Server files prefix:

The prefix that will be used for all of the server configuration files that are generated during the build. For example, if the prefix is myproduct, the files generated will be myproduct.ts1, myproduct.ts2 and myproduct.ts3. You can click the Change button to change the server file prefix. The recommended format is all lowercase alphabetic characters containing no spaces.

Note: Changing the server files prefix after your client has been published will break compatibility between the server data and the TrueUpdate client. Any changes to the prefix should generally be done before distributing your update.

Compress client executable

Compress the client executable during the build process using UPX compression. Generally compressing the file reduces its size by about 50%. You may find an uncompressed format useful if you need to do something to the file such as wrap it using a third party tool.

Note: Changing this setting after the initial release of the client executable will cause the distributed client executable to update itself when run.

Next

Proceed to the next publish wizard page, Upload.

Cancel

Exit the publish wizard and ignore the changes made to any settings.


Upload

Publish Wizard

Overview Output Upload Finished

The Upload publish wizard page is where you can configure all of the locations that you want to automatically publish your server configuration files to. There are several options for publishing your server configuration files such as FTP, SFTP or by copying the file. Normally these locations will be the locations that were configured on the TrueUpdate Servers tab of the Project Settings dialog.

Each of these options contain the settings that were configured on the Upload tab of the Build Settings dialog. You can access the Build Settings dialog by choosing Publish > Settings... from the program menu.

Note: Any changes you make on this page will be saved in the project's build settings.

Note: When you publish automatically through TrueUpdate, there is an additional file that is uploaded that the TrueUpdate publisher uses to determine whether or not new copies of each file needs to be uploaded. This prevents unnecessary uploading if certain server configuration files have not changed. This file's name is composed of the server files prefix with a .tsx file extension. This file is only used by the TrueUpdate design environment and is not used at run time.

Upload Locations

Name

The unique names of each upload location currently defined in your project that can be automatically published to. Each list item contains a checkbox next to it showing which upload locations will be published to on the next build. If you do not wish to publish to a particular upload location, you can uncheck the box next to the name.

Location

The upload locations that are currently configured in the project.

Type

The upload methods currently configured for each of the upload locations (eg. Copy, FTP, or SFTP).

Last Upload

The last time each upload location was published to, in the format MM/DD/YYYY Time. If the upload location has never been published to, "Never" will be displayed.

Add

Add a new upload location to the upload locations list. The following upload types are available:

FTP

Upload the server configuration files to the upload location using FTP when publishing. This opens the Upload Location (FTP) dialog where you can configure its settings.

SFTP

Upload the server configuration files to the upload location using SFTP when publishing. SFTP is similar to FTP but transfers data securely over SSH layer using AES, DES, and BLOWFISH encryption. This opens the Upload Location (SFTP) dialog where you can configure its settings.

File Copy

Copy the server configuration files to a LAN/local folder when publishing. This opens the Upload Location (File Copy) dialog where you can browse for the destination folder.

Remove

Remove the selected location from the upload locations list.

Edit

Edit the properties of the selected upload location. This opens the appropriate Upload Location settings dialog.

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 Upload Finished

The Finished page is the final page of the project wizard. It shows a log of what was done during the build and publish process and lists any errors that occurred.

Open output folder

Automatically open the output folder when the Finished button is clicked.

Show publish report

Automatically open the publish report document when the Finished button is clicked. The publish report outlines what was done during the build and publishing process and where to find the generated files.

Finish

Close the publish wizard and open the output folder and publish report document if those options were selected.


Resources - Overview

Resources

Overview Plugins Includes

Project Resources are those 'behind the scenes' items in your update which allow it to function properly. These include any plugins utilized by your update and script files used.

  • Plugins

  • Includes


Plugins

Resources

Overview Plugins Includes

Action plugins are actions that are external to the TrueUpdate 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 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 TrueUpdate program directory will be available through the design environment by choosing Project > Plugins... from the program menu.

TrueUpdate ships with the Zip Actions Plugin and the Clipboard Actions Plugin, however there are many others that can be integrated into your updates. 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. TrueUpdate ships with the Zip Actions Plugin and the Clipboard Actions Plugin.

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.


Includes

Resources

Overview Plugins Includes

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 update at build time. This enables any code within them to be called anywhere during your update.

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 > Includes... from the program menu.

Each script file that is provided by Indigo Rose contains a summary of its contents at the top of the file which can be viewed in any text editor, such as Notepad. For example, at the beginning of the Detect_Acrobat.lua script file, you will see the following information:

--[[
**********************************************************************************
Function: ir_GetAcrobatVersion()
Purpose: Detects the existence of Adobe Acrobat Reader / Adobe Acrobat
Arguments: None.
Returns: Version number, 0.0.0.0 if Acrobat / Acrobat Reader does not exist
**********************************************************************************
]]

This script file, like many others contains a function that can be called anywhere in your update. 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 update 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 update.
Application.Exit(0);
end

Filename

The full path and filenames of the script files that will be added to your update at build time.

Note: TrueUpdate 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 _TU20_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.

Add

Add a new script file to your project. There are a variety of Indigo Rose created script files that are shipped with TrueUpdate. All available script files can be found in the Scripts folder, normally located in C:\Program Files\TrueUpdate 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 Script File Properties dialog where you can change the location of the selected file, or browse for a different file.

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.


Screens Overview

Screens

Overview Client Screens Server Screens

A screen in TrueUpdate is an interactive graphical user interface that is optionally shown while the update runs. There is no minimum or maximum number of screens that an update must have. There are a variety of screen types available in TrueUpdate that can be used to display or collect information from the user.

Tip: You can also configure the theme you want to use in your update without having to configure each screen manually. Themes are very much like "skins" for your update. You can configure the project theme that you want to apply to all of the screens by choosing Project > Theme... from the program menu. 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.

Screen text can also be translated for each language that is supported by your update. A language selector can be found on the Settings tab of each screen's properties dialog so you can quickly translate this text. You can add additional languages to your update from the Languages tab. You can access the languages tab by choosing Project > Languages... from the program menu.

There are two areas on the design window where you can add and configure the lists of screens that you want to show during your update. These two areas are the Client Screens and Server Screens panels. Each of these panels allow you to add, remove, edit and arrange the order of the lists of screens, as well as import and export the screen's language text. You can switch between the two panels by clicking the appropriate tab at the bottom of the panel. For more information about these two panels, see their respective topics listed below.

There are two areas where screens can be added to your update:

  • Client Screens

  • Server Screens


Client Screens

Screens

Overview Client Screens Server Screens

The Client Screens panel is designed to contain the lists of screens that you want to access from your Client Script . Generally these screens should be designed in such a way that they do not need updating after the client has been distributed. The types of screens that are common in the client are a welcome screen, a download progress screen for downloading the server configuration files and an error handling screen.

Note: If a new client screen is added, or if one of the client screens has been modified after being distributed, the TrueUpdate Client will need to update itself causing the update process to restart after the server configuration files have been downloaded.

When a screen is highlighted in the screens panel, a preview of the selected screen will appear in the Screen Preview panel.

At the top of the Client Screens panel, there are a series of buttons for manipulating the client's screens and screen lists. They are defined as follows:

Add Screen List ( )

Add a new screen list to the client. A screen list contains a group of screens that you want to show in your update. Screen lists allow you group screens together in blocks that you want to show at certain points in your update.

Add Screen ( )

Open the Screen Gallery dialog where you can add a new client screen to your update.

Note: Screens can only be added to a screen list, therefore at least one screen list must be added in order to add a screen.

Remove Screen ( )

Remove the selected screen(s) or screen list(s) from the client.

Note: Removing a screen list will also remove all screens that it contains.

Edit Screen ( )

Open the selected screen's properties dialog where you can configure its settings.

Up ( )

Move the selected screen(s) or screen list(s) up one position.

Down ( )

Move the selected screen(s) or screen list(s) down one position.

Advanced Options ( )

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.


Server Screens

Screens

Overview Client Screens Server Screens

The Server Screens panel is designed to contain the lists of screens that you want to access from your Server Script . Generally these screens should be designed to notify the user of whether or not an update is available, show progress if the system requires updating, and some type of completion screen that notifies the user of whether the update process has completed successfully or has failed.

When a screen is highlighted in the screens panel, a preview of the selected screen will appear in the Screen Preview panel.

All server screens along with the Server Script is stored within the .ts1 server configuration file.

At the top of the Server Screens panel, there are a series of buttons for manipulating the server's screens and screen lists. They are defined as follows:

Add Screen List ( )

Add a new server screen list to your project. A screen list contains a group of screens that you want to show in your update. Screen lists allow you group screens together in blocks that you want to show at certain points in your update.

Add Screen ( )

Open the Screen Gallery dialog where you can add a new server screen to your update.

Note: Screens can only be added to a screen list, therefore at least one screen list must be added in order to add a screen.

Remove Screen ( )

Remove the selected server screen(s) or screen list(s) from your project.

Note: Removing a screen list will also remove all screens that it contains.

Edit Screen ( )

Open the selected screen's properties dialog where you can configure its settings.

Up ( )

Move the selected screen(s) or screen list(s) up one position.

Down ( )

Move the selected screen(s) or screen list(s) down one position.

Advanced Options ( )

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.


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

Table of Screen Dimensions and Coordinates

Here are the sizes and coordinates for the different parts of each screen in TrueUpdate:

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

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

TrueUpdate 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 update needs beyond the standard scenario.

The following screen types are available in TrueUpdate:

  • 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 TrueUpdate 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 clicking the "Add new screen" button on the Screens panel.

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

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 update 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 TrueUpdate 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 clicking the "Add new screen" button on the Screens panel.

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

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("%SourceFolder%").."\\readme.txt");
end

-- Check if the second checkbox was checked.
-- If it is checked, run the application.
if (check02) then
-- The second check box was checked. Run the application.
File.Run(SessionVar.Expand("%SourceFolder%").."\\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 update. 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 TrueUpdate. It was designed to allow you to present a selectable drop down to the user to make choices during the update. 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 clicking the "Add new screen" button on the Screens panel.

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

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 TrueUpdate. 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 clicking the "Add new screen" button on the Screens panel.

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

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 TrueUpdate'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 TrueUpdate. 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.

The Edit Fields screen is available in the Screen Gallery, which can be accessed by clicking the "Add new screen" button on the Screens panel.

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

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 update. 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 TrueUpdate. It was designed to allow you to display license agreement text that the user must read, and agree to, in order to proceed with the update. 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 clicking the "Add new screen" button on the Screens panel.

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

Note: The maximum file size allowed is 10 MB.

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

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 clicking the "Add new screen" button on the Screens panel.

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

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 _SourceFolder\\MyProgOne.exe.
DlgListBox.SetItemProperties(CTRL_LIST_BOX, 1, {ItemData=_SourceFolder.."\\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 list box 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 list box 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 list box 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 TrueUpdate. It was designed to provide a visual representation of progress for various tasks during the update. This screen is useful in situations where large amounts of script need to be executed, or for actions that may take longer to complete, such as a file download or file copy. The progress bars screen can be configured to show one, two or no progress meters.

This screen type is typically used to show progress during the downloading of files, but can be used for anything you wish.

The Progress Bars screen is available in the Screen Gallery, which can be accessed by clicking the "Add new screen" button on the Screens panel.

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 TrueUpdate 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 TrueUpdate 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 update.

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

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 TrueUpdate 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 clicking the "Add new screen" button on the Screens panel.

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

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 TrueUpdate. 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 TrueUpdate. 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 clicking the "Add new screen" button on the Screens panel.

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

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

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 TrueUpdate 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 clicking the "Add new screen" button on the Screens panel.

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

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

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 TrueUpdate. 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 TrueUpdate. These include the "Welcome", and "Update Finished" screens.

The Static Text screen is available in the Screen Gallery, which can be accessed by clicking the "Add new screen" button on the Screens panel.

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

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


Overview

Scripts

Overview Client Script Server Script

TrueUpdate contains two main script tabs for adding action script to your update. These tabs contain all of the features of the action editor, but are represented in a tabbed view rather than a window. All of its features can be accessed from either the right-click context menu, or from the Script or Edit program menus.

The Client Script tab contains the action script that will be built into the client's data file whereas the Server Script tab's action script is stored in the server configuration files.

The Client Script and Server Script tabs are part of all projects, however you can also add custom script tabs that will become part of the server configuration files. Custom script tabs are useful for keeping things organized, or for when your action script becomes too large to maintain efficiently.

The following script tabs are available in TrueUpdate. Custom script tabs are discussed under the Server Script topic:

  • Client Script

  • Server Script


Client Script

Scripts

Overview Client Script Server Script

The Client Script tab is designed to contain the action script that is run by the client when the update is launched. Generally this script will consist of actions to show client screens such as a welcome screen and a progress screen used to download the server configuration files using the Screen.Show action. If the download of the server configuration files is successful, the Server Script would be run using the TrueUpdate.RunScript action.

Generally this script should be written in such a way that it does not need updating after the client has been distributed.

Note: If the client script has been modified after being distributed, the TrueUpdate Client will need to update itself causing the update process to restart after the server configuration files have been downloaded.

The Client Script contains all of the features of the action editor, but is represented in a tabbed view rather than a window. All of its features can be accessed from either the right-click context menu, or from the Script or Edit program menus.


Scripts

Overview Client Script Server Script

Server Script

The Server Script tab is designed to contain the action script that determines whether or not an update is available, and actually applying the update. This script can be run from the Client Script using the TrueUpdate.RunScript action. The server script is normally the component that is updated each time a new version of your software is released. The server script is also a component of the server configuration files that are downloaded and loaded using the TrueUpdate.GetServerFile action.

Generally this tab will contain action script to determine which version of the software is currently installed on the client system. This can be done using various methods such as comparing file versions, file dates, Registry entries etc. The value read from the user's system would then be compared to some target value that will determine whether or not an update is available.

Server Scripts will also control the displaying of all Server Screens using the Screen.Show action. For example, once the server script has determined that an update is required, you would normally notify the user that there is an update available. Other common screens that may be shown are progress screens for downloading an installer/patch file, and status screens to notify the user of whether or not the update was successful or failed for some reason.

The Server Script contains all of the features of the action editor, but is represented in a tabbed view rather than a window. All of its features can be accessed from either the right-click context menu, or from the Script or Edit program menus.

Custom Script

For larger updates you may find that your Server Script is becoming too large. For these situations, TrueUpdate allows you to create additional custom server scripts for organizing your code. You can add a custom server script to your project by selecting Script > New from the program menu. Custom scripts can be called using the same method as the Server Script, using the TrueUpdate.RunScript action. All custom scripts created become part of the server configuration files.


Tools - Overview

Tools

Overview

The following tools are available in TrueUpdate:

  • Calculate File CRC

  • Calculate File MD5

  • Get File Version


Calculate File CRC

Overview

File name:

The full path to the file you want to calculate the CRC value of. You can click the Browse button to select a file from your system.

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

File name:

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.

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 update. You can paste the value by selecting Paste from the right-click context menu, or using Ctrl+V on your keyboard.


Get File Version

Overview

File name:

The full path to the file you want to get the version of. You can click the Browse button to select a file from your system.

File version:

The version number of the specified file.

Copy

Copies the value in the File version field to the Windows clipboard so you can paste it somewhere within your update. You can paste the value by selecting Paste from the right-click context menu, or using Ctrl+V on your keyboard.


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 TrueUpdate. The first type are called Global Variables that are expanded once at the beginning of the update. 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 update process. They are most commonly used to display dynamic content on screens.

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 update 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 TrueUpdate:

_ClientRestarted

Whether or not the client has been restarted after the client executable or client .dat has been updated after downloading the server configuration files. If this variable contains true the client has been restarted, and if it contains false, it has not. This variable is useful if you would like to skip certain steps in the Client Script such as showing the Welcome screen.

_CommandLineArgs

A numerically indexed table that contains the command line arguments passed into the update 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.

_IR_ProductID

This variable contains the string "TU30" when used in TrueUpdate. 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.

_ProgramFilesFolder

The user's Program Files folder (typically, this is something like "C:\Program Files").

_SourceDrive

The drive that the update executable was run from (e.g. "C:" or "D:").

_SourceFilename

The full path and filename of the update executable (e.g. "C:\Downloads\update.exe").

_SourceFolder

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

_SuppressErrorDialogs

Whether or not dialog error messages will be shown from script errors. Initially this value is set to the boolean value false, but if set to true, script error dialogs will be suppressed.

Note: This only affects script errors and does NOT suppress action dialogs or screens.

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

_UseAutoProxy

Controls whether or not TrueUpdate will use autoproxy support when accessing files from the Internet. If the /NOAUTOPROXY command line option is passed to the client executable _UseAutoProxy will be initialize to false. Setting _UseAutoProxy to true will override the /NOAUTOPROXY option. This variable can turn the autoproxy support on or off as needed.

Note: TrueUpdate will default to using a direct connection if attempts using the autoproxy fail, so it is not normally necessary to disable the autoproxy.

_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. This type of variable was designed to be used on screens, while global variables were designed to be used in action script.

While there are predefined session variables available to use, you can also create custom session variables at design time and run time. At design time, they can be defined on the Session Variables tab of the Project Settings dialog. At run time, you can create and manipulate session variables using the available SessionVar actions.

Note: If a session variable used on a screen needs to be set to a different value, it must be set prior to the screen's displaying, and all of its events. Another option is to set the text of the screen control using the appropriate Dlg***.SetProperties action. Any changes made to a session variable on a screen after the screen has been created (just before the On Preload event) will have no effect.

The following pre-defined session variables are available in TrueUpdate:

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

%Copyright%

The copyright message for your product. The value of this variable is set on the Session Variables tab of the Project Settings dialog.

%DAOPath%

The path to the user's DAO (Data Access Objects) directory.

%DesktopFolder%

The path to the user's Desktop folder. 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 updating. 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 update executable was run from (e.g. "C:" or "D:").

%SourceFolder%

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

%SourceFilename%

The full path, including the filename, for the current update executable.

For example, if the user was running "update.exe" from "C:\Downloads", %SourceFilename% would be expanded to "C:\Downloads\update.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.

%WindowsFolder%

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


Design-time Constants

Variables

Overview Global Variables Session Variables Design-time Constants

Design-time constants are similar to session variables, but instead of being converted to values at run time, design-time constants get converted at build time. We call them design-time constants because the names you give them only exist at design time. At build time, the name of each design-time constant is replaced by the value that was assigned to it.

Tip: You can also define custom design-time constants on the Constants tab, found by choosing Publish > Settings... from the program menu.

The following design-time constants are available in TrueUpdate:

#ASC????#

This is a special set of design-time constants. When a constant's name starts with "#ASC", TrueUpdate interprets the value assigned to that constant as the ASCII value of a character. Wherever you use that constant, TrueUpdate 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, TrueUpdate 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 update executable is built.

#CURRENTHOUR#

A number representing the current hour in 24-hour time (e.g. 4:00 PM is 16), calculated when the update executable is built.

#CURRENTMINUTE#

The current minute, calculated when the update 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 update 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 update executable is built. January is represented by "01" and December is represented by "12".

#CURRENTSECOND#

The current second, calculated when the update 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 update executable is built.

#DATE#

The current date on your development system when the update executable is built. It's in the format MM/DD/YY. So, if you built the update on May 23, 2004, #DATE# would be "05/23/04".

#EUROPEANDATE#

The current date on your development system when the update executable is built, in the European dating format: DD/MM/YY. For example, if you built the update on May 23, 2004, #EUROPEANDATE# would be "23/05/04".

#ISODATE#

The current date on your development system when the update executable is built, in the ISO format: YYYY-MM-DD. For example, if you built the update on May 23, 2004, #ISODATE# would be "2004-05-23".

#JULIANDATE#

The current date on your development system when the update 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 updates that expire a certain number of days after they are created. To calculate the number of days that have elapsed since the update executable was generated, use the formula %JulianDate% - #JULIANDATE#.

#PROGRAMFILESDIR#

The path to the Program Files directory on your development system.

#PROJECTFILEDIR#

This is path to the TrueUpdate project (.tu2) 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 file (.tu2) and the files in your update 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.

#SYSDIR#

The path to the system directory on your development system.

#TUDIR#

The path to the directory where TrueUpdate is installed on your development system. Usually this will be "C:\Program Files\TrueUpdate 3.0".

#WINDIR#

The path to the Windows directory on your development system.


Miscellaneous

Contents

Please select one of the following subjects:

ASCII Table

Authenticode Code Signing

Callback Functions

INI Files

Input Mask

Language ID Codes

MD5 Digest

Secure Transfer Methods

Server Configuration Files

System Restore Monitored File Extensions

Virtual Key Codes

XML Actions Concepts


ASCII Table

Miscellaneous

Contents ASCII Table

ASCII stands for American Standard Code for Information Interchange. Computers can only understand numbers, so an ASCII code is the numerical representation of a character such as 'a' or '@' or an action of some sort. Below is the standard ASCII character set and includes descriptions of the first 32 non-printing characters.

Decimal | Hex | Character |
0 | 0 | NUL | (null)
1 | 1 | SOH | (start of heading)
2 | 2 | STX | (start of text)
3 | 3 | ETX | (end of text)
4 | 4 | EOT | (end of transmission)
5 | 5 | ENQ | (enquiry)
6 | 6 | ACK | (acknowledge)
7 | 7 | BEL | (bell)
8 | 8 | BS | (backspace)
9 | 9 | TAB | (horizontal tab)
10 | A | LF | (NL line feed, new line)
11 | B | VT | (vertical tab)
12 | C | FF | (NP form feed, new page)
13 | D | CR | (carriage return)
14 | E | SO | (shift out)
15 | F | SI | (shift in)
16 | 10 | DLE | (data link escape)
17 | 11 | DC1 | (device control 1)
18 | 12 | DC2 | (device control 2)
19 | 13 | DC3 | (device control 3)
20 | 14 | DC4 | (device control 4)
21 | 15 | NAK | (negative acknowledge)
22 | 16 | SYN | (synchronous idle)
23 | 17 | ETB | (end of trans. block)
24 | 18 | CAN | (cancel)
25 | 19 | EM | (end of medium)
26 | 1A | SUB | (substitute)
27 | 1B | ESC | (escape)
28 | 1C | FS | (file separator)
29 | 1D | GS | (group separator)
30 | 1E | RS | (record separator)
31 | 1F | US | (unit separator)
32 | 20 | Space |
33 | 21 | ! |
34 | 22 | " |
35 | 23 | # |
36 | 24 | $ |
37 | 25 | % |
38 | 26 | & |
39 | 27 | ' |
40 | 28 | ( |
41 | 29 | ) |
42 | 2A | * |
43 | 2B | + |
44 | 2C | , |
45 | 2D | - |
46 | 2E | . |
47 | 2F | / |
48 | 30 | 0 |
49 | 31 | 1 |
50 | 32 | 2 |
51 | 33 | 3 |
52 | 34 | 4 |
53 | 35 | 5 |
54 | 36 | 6 |
55 | 37 | 7 |
56 | 38 | 8 |
57 | 39 | 9 |
58 | 3A | : |
59 | 3B | ; |
60 | 3C | < |
61 | 3D | = |
62 | 3E | > |
63 | 3F | ? |
64 | 40 | @ |
65 | 41 | A |
66 | 42 | B |
67 | 43 | C |
68 | 44 | D |
69 | 45 | E |
70 | 46 | F |
71 | 47 | G |
72 | 48 | H |
73 | 49 | I |
74 | 4A | J |
75 | 4B | K |
76 | 4C | L |
77 | 4D | M |
78 | 4E | N |
79 | 4F | O |
80 | 50 | P |
81 | 51 | Q |
82 | 52 | R |
83 | 53 | S |
84 | 54 | T |
85 | 55 | U |
86 | 56 | V |
87 | 57 | W |
88 | 58 | X |
89 | 59 | Y |
90 | 5A | Z |
91 | 5B | [ |
92 | 5C | \ |
93 | 5D | ] |
94 | 5E | ^ |
95 | 5F | _ |
96 | 60 | ` |
97 | 61 | a |
98 | 62 | b |
99 | 63 | c |
100 | 64 | d |
101 | 65 | e |
102 | 66 | f |
103 | 67 | g |
104 | 68 | h |
105 | 69 | i |
106 | 6A | j |
107 | 6B | k |
108 | 6C | l |
109 | 6D | m |
110 | 6E | n |
111 | 6F | o |
112 | 70 | p |
113 | 71 | q |
114 | 72 | r |
115 | 73 | s |
116 | 74 | t |
117 | 75 | u |
118 | 76 | v |
119 | 77 | w |
120 | 78 | x |
121 | 79 | y |
122 | 7A | z |
123 | 7B | { |
124 | 7C | | |
125 | 7D | } |
126 | 7E | ~ |
127 | 7F | DEL |


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 updates. Due to the changes made to Internet Explorer in Windows XP SP2, and the Windows Vista or later OS's, when a customer downloads and runs your software, they will be presented with a warning dialog asking the user if they really want to run your software. On that dialog, they will see “Unknown Publisher” if it is not signed. On the other hand, if you do sign your code, they will instead see your company name and an optional web link to follow for more information. If you plan to distribute on Windows Vista or later, another point of consideration beyond user experience, is the fact that Windows Vista or later has the ability to prevent any unsigned applications from launching with full privileges. This may impact both the updating 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 Updates

Once the Authenticode file signing tool is installed on your system, you are ready to start signing your code.

  1. Before publishing your update, select Publish > Settings from the menu and click on the Code Signing tab.

  2. Check the "CodeSign updates" checkbox and fill in the available fields including selecting the desired tool's location on your system.

  3. Publish your final update by selecting Publish > Build.

Tip: See the Code Signing Preferences page for configuring defaults to use for code signing your updates 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 client update executable.

Alternatively, you could simply upload the update to a web site and then download and run it from a computer using Windows XP SP2, or Windows Vista or later. You'll see the same information.

Getting More Information

There are many good resources on the Internet for finding out more about code signing, Authenticode, Windows XP/Vista or later, Security and related issues. Here are a few places to start.

  • MSDN: Introduction to Code Signing

  • Certify your Software Integrity with Thawte Code Signing Certificates

  • MSDN: Cryptography Tools (Windows)

  • MSDN: SignTool (Windows)

  • MSDN: File Signing Tool (Signcode.exe)

  • Microsoft: Signing and Checking Code with Authenticode

Copyright © 2012 Indigo Rose Software. All rights reserved.


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 TrueUpdate actions contain a Callback Function parameter:

  • File.Copy

  • File.Delete

  • File.Find

  • File.Install

  • File.Move

  • Folder.DeleteTree

  • Folder.Find

  • FTPWI.Download

  • FTPWI.GetFileSize

  • HTTP.Download

  • HTTP.DownloadSecure

  • HTTP.GetFileSize

  • HTTP.GetFileSizeSecure

  • TrueUpdate.GetServerFile


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: TrueUpdate 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.


Secure Transfer Methods

Miscellaneous

Contents Secure Transfer Methods

TrueUpdate contains two methods for transferring files securely. A description of each of these methods can be found below:

HTTPS

The secure hypertext transfer protocol (HTTPS) is a communications protocol designed to transfer information securely between computers over the World Wide Web. HTTPS is simply HTTP using a Secure Socket Layer (SSL) to perform the client-server communication. The secure socket layer ensures that the information transmitted over HTTPS is encrypted so it cannot be intercepted on the way to its destination.

SFTP

SFTP, or secure File Transfer Protocol, is a transfer method that uses SSH to transfer files using AES, DES, and BLOWFISH encryption. Unlike standard FTP, SFTP encrypts the data and commands that are sent to the server. This prevents passwords and sensitive information from being transmitted over the network in an unsecure way. Although SFTP is functionally similar to FTP, it is a different protocol; in order to transfer files to a server using SFTP, the server must support the SFTP protocol. You can't use a standard FTP client to send files to an SFTP server, nor can you connect to an FTP server with a client that supports only SFTP. TrueUpdate's implementation of SFTP uses SSH2.

SSH and SSH2

The SSH (Secure Shell) protocol is a secure replacement for telnet and the Berkeley r-utilities (rlogin, rsh, rcp, and rdist). It provides an encrypted channel for logging into another computer over a network, executing commands on a remote computer, and moving files from one computer to another. SSH provides strong host-to-host and user authentication as well as secure encrypted communications over an insecure Internet.

SSH2 is a more secure, efficient, and portable version of SSH.


Server Configuration Files

Miscellaneous

Contents Server Configuration Files

The server configuration files are what TrueUpdate refers to as the encrypted files that are published to your server to control whether or not an update needs to take place. Normally the Client Script will contain a TrueUpdate.GetServerFile action that downloads and loads these files into the TrueUpdate client engine and a TrueUpdate.RunScript action to run the Server Script.

The server configuration files consist of three encrypted files, each containing the same name but with different file extensions. The name that is given to these files is referred to as the server file prefix and the extensions given to these files are .ts1, .ts2 and .ts3. Each of these files are defined as follows:

Note: You must make sure that the *.ts* extensions are part of the MIME types list on your server. If files with these extensions are not part of the list, you will receive error number 3624.

<<server file prefix>>.ts1

The .ts1 file contains the encrypted server data. This means that it contains the Server Script and Server Screens. This is the file that is normally updated each time a new version of your software is released.

<<server file prefix>>.ts2

The .ts2 file contains all of the client data in encrypted form. This means that it contains the Client Script, Client Screens and all other project data. This is all contained within the client's .dat file. If for any reason the client data needed to be updated, this will allow the client to update itself when the TrueUpdate.GetServerFile action is called. When the client data file is updated, the update process will restart automatically and the global variable _ClientRestarted will be set to true. TrueUpdate is able to tell whether or not there is a newer client data file from information stored in the .ts1 file. Generally it is best to design your update so that the client data does not require updating after it has been distributed, however cases may arise when this is needed.

<<server file prefix>>.ts3

The .ts3 file contains the client executable, which is the TrueUpdate client's runtime file. TrueUpdate is able to tell whether or not there is a newer client executable file from information stored in the .ts1 file. Normally the client executable does not need updating, but occasionally new versions become available through service releases of the TrueUpdate program. This means that the client will always stay up-to-date with the latest release of TrueUpdate's run time. The TrueUpdate client will also be updated if the Compress client executable setting changes, the Requested User Privilege Level setting on the Advanced tab of Project Settings, information on the Resources tab of the Build Settings, or changes to the Code Signing settings of the Build Settings. If the client executable is updated, the update process will restart automatically and the global variable _ClientRestarted will be set to true.


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


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


Command Line Options

Overview

TrueUpdate'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 update and build process.

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

The available command line options are grouped into the following two categories:

  • Client Update Command Line Options

  • Unattended Build Options

Client Update Command Line Options

The following command line options are supported by the TrueUpdate client:

/DATFILE:<<Filename>>

Allows you to specify a client data file for the client executable to load. By default the client looks for a file with the same name as the executable but with the .dat file extension (Update.exe = Update.dat).

/NOFOCUS

Tells the update not to steal focus from any currently running application that has focus. This option will also not show a taskbar representation (regardless of the Taskbar Visibility) unless you show a screen.

Note: This command line option will cause any debug actions used in your update not to function.

/NOAUTOPROXY

Forces all actions that use HTTP connections in the update not to use the autoproxy feature.

/T:<<file path>>

Every update executable requires some temporary space on the user's hard drive during the update process. By default, TrueUpdate uses the user's TEMP directory for extracting temporary files and other miscellaneous operations. You can force the update 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 update 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:\Program Files\MyProduct\update.exe" "/T:C:\My Temp Dir"

(forces the update to use "C:\My Temp Dir" for temporary files)

Unattended Build Options

The following command line options are supported by TrueUpdate'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 TrueUpdate build process. See the Build Error Codes topic for information on what codes can be returned.

/BUILD

Tells TrueUpdate to build the project file passed in on the cmd line or from a batch file. For example:
"C:\Program Files\TrueUpdate 3.0\TrueUpdate.exe" /BUILD "C:\TestProj.tu2"

/LOG:<<log file path>>

Specifies a log file to output build status to. If the file exists, the output will be appended to it. If the file does not exist, it will be created. For example:

"C:\Program Files\TrueUpdate 3.0\TrueUpdate.exe" /BUILD "C:\TestProj.tu2" "/LOG:C:\output\Log.txt"

/STDOUT

Makes the build status go to the standard output device (console). For example:

"C:\Program Files\TrueUpdate 3.0\TrueUpdate.exe" /BUILD "C:\TestProj.tu2" "/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
#UPDATENAME#=foobar2002update.exe
#BUILD#=release

When you use the /CONST option along with /BUILD, the specified project file is loaded into TrueUpdate, the constants described in the specified unattended-build INI file are set, and the update executable is generated-all without any interaction.

For example:
"C:\Program Files\TrueUpdate 3.0\TrueUpdate.exe" /BUILD "C:\TestProj.tu2" "/CONST:C:\MyProj\Config.ini"

Note: If you require the value to be a string and have defined the constant as something like "My Value" (including quotes) on the Constants tab of Build Settings, you must use two sets of quotes when setting the value through the INI file, such as: MY_CONSTANT=""My New Value""


Build Error Codes

Overview

Tip: In order for the TrueUpdate client to function correctly, a section of its resources must be modified when publishing. If you are trying to publish on an unsupported operating system below Windows 2000, or are having problems, you can set a hidden preference that will allow a build to complete with warnings, instead of fatal errors when updating its resources. Open your TrueUpdate preferences file (see the Folders preference for its current location) in a text editor and locate the XML tag "SupressResourceStampError". Then change its value from 0 to 1. While this allows you to publish, skipping this crucial step means that the client will always require updating itself when it is run.

The following error codes may be generated during the build or publish process:

1000

"Build cancelled."

1010

"Invalid internal pointer."

1011

"Failed to copy runtime engine."

1012

"Failed to open configuration file for writing: <<filename>>."

1022

"Failed to load global include file: <<filename>>."

1023

"Could not locate constants file:<<filename>>."

1024

"Output folder cannot be empty."
"Output folder does not exist and cannot be created."

1026

"Could not find unattended build constants file: <<constants file>>."

1027

"Could not read build constants file: <<constants file>>. "

1030

"Client file name cannot be empty."
"Client file name contains invalid characters."

1031

"Server file name cannot be empty."
"Server file name contains invalid characters."

1032

"The Project theme <<theme name>> does not exist in the specified location <<theme location>>."

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

2053

"Image file not found (screen: <<screen name>>) <<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>>."

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

4000

"Invalid internal pointer to server file."

4001

"Copying: <<.ts1 file source>> To: <<.ts1 destination>> failed. Reason: <<reason for failure>>"

"Uploading: <<.ts1 file source>> To: <<.ts1 destination>> failed. Reason: <<reason for failure>>"

4002

"Copying: <<.ts2 file source>> To: <<.ts2 destination>> failed. Reason: <<reason for failure>>"

"Uploading: <<.ts2 file source>> To: <<.ts2 destination>> failed. Reason: <<reason for failure>>"

4003

"Copying: <<.ts3 file source>> To: <<.ts3 destination>> failed. Reason: <<reason for failure>>"

"Uploading: <<.ts3 file source>> To: <<.ts3 destination>> failed. Reason: <<reason for failure>>"

4004

"Error connecting to SFTP host: <<host name>>."

4100

"Failed to resource stamp runtime engine."

4101

"Failed to update runtime engine resources - operation not supported on build operating system."

4200

"Error UPX executable not found."

4201

"Error UPX compression failed."

4300

"Code sign tool executable does not exist: <<filename>>"

4301

"Code signing certificate file does not exist or is not defined."

4302

"Code sign private key file does not exist or is not defined."

4303

"Code sign output file does not exist."

4304

"Execute program error executing code signing tool."

7000

"Screen <<screen name>> uses top banner style but no image file specified."

7001

"Screen <<screen name>> uses side banner style but no image file specified."

7002

"Screen <<screen name>> uses banner style "none" but no image file specified."

7100

"Script Warning: Script Warning: [Location=<<location>>, Event <<event>>] Warning Detail: [Script is empty]"

7101

"No TrueUpdate Servers have been configured."

7250

"Writing manifest to executable only supported on Windows 2000 and greater. Manifest will not be updated."

Note: See Requested User Privilege Level (Vista) for more information on update manifests.

7260

"Failed to write permissions manifest to update."

Note: See Requested User Privilege Level (Vista) for more information on update manifests.

7400

"Warning: Resource Stamping Skipped - operation not supported on build operating system."

7401

"Warning: Failed to resource stamp runtime engine."

7406

"Warning: Server .ts3 file is a newer version than the local copy." (It will not be updated.)


Update Return Codes

Overview

The following process return codes may be returned by a TrueUpdate application:

0

The update completed successfully without any errors.

5

The update was aborted by the user.

Note: This return code is set in the default project script using the numeric constant EXIT_REASON_USER_ABORTED.

7

The update was built with the evaluation version and has reached the end of its evaluation period.

10

The update was aborted because the client executable needed to be updated.

11

The update was aborted because the client data file needed to be updated.

12

The update was aborted because both the client executable and client data file needed to be updated.

103

The update executable contains an invalid name.

104

A plugin used in the update failed to be initialized.

105

Failed to create temporary resource folder.

107

Failed to find update data file.

109

Failed to load update data file.

111

Failed to extract resource files.


Windows Basics

Overview

In order to use TrueUpdate 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 TrueUpdate 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 TrueUpdate (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 TrueUpdate (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 TrueUpdate and "dropping" it into the design environment.

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 TrueUpdate 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 TrueUpdate: 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 TrueUpdate is installed by default is:
    C:\Program Files\TrueUpdate 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 TrueUpdate application from the Program Files folder would be:
    TrueUpdate 3.0\TrueUpdate.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 TrueUpdate folder on a C: drive which is shared as "D2" on a computer named "R2" would be:
    \\R2\D2\Program Files\TrueUpdate 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 TrueUpdate, 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. TrueUpdate uses an industry-standard CRC-32 algorithm which generates CRC values that are 32 bits in length. This means that one in every 4,294,967,296 files could have the same CRC "fingerprint."

A file doesn't have to change much for its CRC value to be different. In fact, if even just one bit in a file changes, the CRC value for that file will change as well. If all you did was change one letter in a readme.txt file between version 1 and version 2, the CRC value for that readme.txt file would be completely different.

CRC values can be calculated for any type of file.

Although the chances of any two files having the same CRC value are incredibly small, the CRC value alone isn't enough to guarantee an accurate identification. If you need to be absolutely sure, check the CRC in addition to other information about the file, such as the size of the file in bytes and its location on the user's system.

Next: Overview


Copyright Information

Copyright Info

Proprietary Notice

The software described in this document is a proprietary product of Indigo Rose Software Design Corporation and is furnished to the user under a license for use as specified in the license agreement. The software may be used or copied only in accordance with the terms of the agreement.

Information in this document is subject to change without notice and does not represent a commitment on the part of Indigo Rose Software Design Corporation. No part of this document may be reproduced, transmitted, transcribed, stored in any retrieval system, or translated into any language without the express written permission of Indigo Rose Software Design Corporation.

Trademarks

TrueUpdate 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-2012 Indigo Rose Software Design Corporation.
All Rights Reserved.

LUA is copyright © 2012 Tecgraf, PUC-Rio.

UPX executable compression (http://upx.sf.net) copyright © 1996-2012 Markus Franz Xaver Johannes Oberhumer, copyright © 1996-2012 Laszlo Molnar, copyright © 2000-2012 John F. Reiser. All Rights Reserved.


Ordering Information

Ordering Information

Benefits of Ordering

When you order TrueUpdate you will receive:

  • TrueUpdate program with the latest revisions and enhancements.

  • A license to distribute, royalty-free, the updates that you create with TrueUpdate.

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

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

TrueUpdate User's Guide:

Pages: 267
Perfect bound
Catalogue #: 05-0107
ISBN: 1-4120-5212-2

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 TrueUpdate 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

TrueUpdate Development System

The minimum and recommended system requirements for the TrueUpdate development system are:

Minimum

Windows 2000, Windows XP, Windows Vista, Windows 7 or Windows 8
Pentium processor (or equivalent)
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
Mouse

TrueUpdate Client Application

The minimum system requirements for the TrueUpdate client application are:

Minimum

Windows 95, 98, Me, NT 4.0 (SP6), Windows 2000, Windows XP, Windows Vista, Windows 7, Windows 8
Internet Explorer 4.0 or greater
Pentium processor (or equivalent)
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.


What Is Converted

Importing TrueUpdate 1.0 Projects

Overview What Is Converted What Is Not Converted

This section will outline all of the information that gets converted from TrueUpdate 1.0 to TrueUpdate 3.0. For a list of options that are not converted, please see the next section, What Is Not Converted.

This topic covers the conversion in the following areas of a TrueUpdate 1.0 project:

  • Client Configuration Utility

    • Product Info

    • Interface

    • Messages

    • Variables

    • Build

  • Server File Editor

    • Actions

Client Configuration Utility

Product Info

General Information:

The General Information settings are converted to the following TrueUpdate 3.0 Session Variables:

Product name = %ProductName%

Company name = %CompanyName%

Company URL = %CompanyURL%

Company phone = %CompanyPhone%

Copyright notice = %Copyright%

All of the above session variables can be found on the Session Variables tab. You can access the Session Variables tab by selecting Project > Session Variables... from the program menu.

Server File Locations:

The server file locations are converted to settings located in two areas in TrueUdate 3.0: TrueUdate servers and automatic upload locations.

This conversion is basically a one-to-one conversion with three differences:

  1. Server file locations in TrueUpdate 1.0 did not have an ID, so the location specified in the v1.0 project is used as the ID in v3.0.

  2. In TrueUpdate 1.0 you needed to specify the full path and filename of the server file, whereas in v3.0, you only need to specify the folder where the server configurations files will exist. The conversion process will drop the filename from the server file location.

  3. Server file locations in TrueUpdate 1.0 have conditions associated with them, however since TrueUpdate servers do not have conditions associated with them in v3.0, this setting is not converted. Instead, TrueUpdate runs through the server locations given the order on the TrueUpdate Servers dialog, until one server is successfully accessed.

Automatic upload locations are a new feature in TrueUpdate 3.0, and usually correspond to the TrueUpdate servers that have been defined. So during the conversion process, TrueUpdate will convert the server file locations into approximate automatic upload locations. Since many of the parameters required by the automatic upload locations are not available in TrueUpdate 1.0, a "best guess" attempt at these settings is made. As a result, it is important to edit each automatic upload location after the conversion process has completed.

Interface

The interface is one of the most obvious differences between TrueUpdate 1.0 and 3.0. One of the design goals of version 3.0 was to increase both the work flow, and ease of use of the user interface.

Screens:

The dialog interface will not be converted into TrueUpdate 3.0 since there is not an applicable interface. If your project used the dialog interface, it is necessary to convert this manually using Dialog actions. Please see the project wizard, or one of the many templates in TrueUpdate 3.0 for information on how to accomplish this.

All of the wizard interface screens will be converted into TrueUpdate 3.0, even if they were not enabled in TrueUpdate 1.0. If they were not enabled in TrueUpdate 1.0, they will be converted to the "Excluded Wizard Screens" screen list. The Update Canceled screen will be converted to the "Excluded Wizard Screens" screen list, even if it is enabled. Due to the new, more configurable user interface in TrueUpdate 3.0, all enabled screens will be converted into screen lists on either the client side or server side.

The images associated with screens in TrueUpdate 1.0 are not converted due to the addition of the themes in v3.0. Instead, the converted screens will all be set to use the default project theme.

Default Run Mode:

Since the dialog interface is not converted, the Default Run Mode setting is not converted either.

Custom Icon:

The custom icon will be converted over to TrueUdpate 3.0.

User Configuration:

The user configuration settings are not converted over into TrueUpdate 3.0, as they are not required for the most part.

Messages

Only the messages associated with wizard screens are converted into TrueUpdate 3.0. This preserves any text that you associated with screens in TrueUpdate 1.0, along with the any multilingual support that you added.

All languages that are supported in your TrueUpdate 1.0 project will also be supported in the converted project.

Variables

Custom variables are either converted into Lua variables or session variables in TrueUpdate 3.0. For the most part they will be converted into Lua variables unless they are overriding built-in session variables in TrueUpdate 3.0. All variables will have their values assigned at the beginning of the Client Script.

Build

Output:

The output folder and the client executable filename will convert properly into TrueUpdate 3.0.

Debug Mode:

Debug mode is not converted into TrueUpdate 3.0 because there is no equivalent setting. Instead, debugging actions are available.

Server File Editor

When working with the Server File Editor in TrueUpdate 1.0, versions were identified by creating version identifiers and then associating a series of actions that were executed when that version was identified.

This general framework is converted for you by converting the actions from each version, into script tabs in TrueUpdate 3.0. The name of each script tab will be the version label, providing it is unique. If it is not unique, a numeric index is appended to its name. Then all of the actions that were on the actions tab will be converted into TrueUpdate 3.0 actions on that script tab.

Version identifiers are converted to If statements on the Server Script which will determine which script tab to run.

The update size associated with each version is converted to a SessionVar.Set action that will set the session variable %UpdateSize% to be whatever was entered in the Update size field of the v1.0 project.

Actions

Most actions from TrueUpdate 1.0 are converted over to TrueUpdate 3.0 with a few exceptions that are listed in the What Is Not Converted topic.


What Is Not Converted

Importing TrueUpdate 1.0 Projects

Overview What Is Converted What Is Not Converted

This topic outlines the elements of a TrueUpdate 1.0 project that are not converted automatically. Choose one of the areas below for a description of its non-converted content:

  • More Info Link

  • Built-in Variables

  • Actions

  • Screens

  • Build

  • Conclusion

More Info Link

The More info link and the Notes fields in the General area of the server file editor are not converted to TrueUpdate 3.0.

Built-in Variables

Built-in variables are converted into either Session Variables or LUA variables in TrueUpdae 3.0. Generally the built-in variables from TrueUpdate 1.0 are available as built-in session variables or built-in global variables in TrueUpdate 3.0. Whenever possible, the built-in variables from TrueUpdate 3.0 are used in the conversion.

When using a built-in variable from TrueUpdate 1.0 that is not available in v3.0, actions will be created to reproduce their values.

Actions

Most actions from TrueUpdate 1.0 are converted over to TrueUpdate 3.0, with a few exceptions:

  1. Upload File FTP – There is no built-in FTP upload actions in TrueUpdate 3.0, however an FTP plugin is available if this action is a necessity.

  2. GOTO Label – There is no GOTO Label action in TrueUpdate 3.0. Given the available control structures and looping structures of TrueUpdate's new scripting language, this action should not be needed.

  3. Send Email – There is no send email action in TrueUpdate 3.0. Since sending email in a generic way is not reliable, many have switched to using the HTTP.Submit action for handling this type of communication.

  4. Generate Random Value – The String based on mask option is not supported in TrueUpdate 3.0, however the Number between values option is.

  5. Zip Actions – The Zip actions available in v1.0 are not built into TrueUpdate 3.0. However, by default the Zip plugin is shipped with version 3.0 and can be enabled by choosing Project > Plugins... from the program menu. When a Zip action is converted to v3.0, the Zip plugin will automatically be included in your project.

  6. Download File HTTP – The addition of the %NextDownloadWebFile% variable in TrueUpdate 1.0 makes the conversion of this action somewhat difficult. Every attempt has been made to ensure that this important action converts properly, however if you do use this action, we recommend that you do not use the converted version of it. Instead, manually rewrite the action using the v3.0 version of the action.

Screens

The dialog interface available in TrueUpdate 1.0 is not converted. Instead, the project will be converted into a v3.0 project containing only wizard screens. However, TrueUpdate 3.0 does have the capability to show dialogs instead of wizard screens if that is the design you prefer. Instead of dialogs being an interface type, they are simply shown using Dialog.Message actions in v3.0.

No screen images are brought over in the conversion because of the addition of project themes in TrueUpdate 3.0. Instead, all wizard screens are configured to use the default project theme. However, you can certainly customize your project theme after the conversion if you are unhappy with the default project theme. You can either select an alternate theme, or customize each screen individually.

Default Run Mode:

Since the dialog interface is not converted, the Default Run Mode setting is not converted either.

User Configuration:

The user configuration settings are not converted over into TrueUpdate 3.0, as they are not required for the most part. Now TrueUpdate 3.0 goes through Internet Explorer's connection settings, which eliminates many user proxy issues.

Build

Debug Mode:

Debug mode is not converted into TrueUpdate 3.0 because there is no equivalent setting. Instead, debugging actions are available.

Conclusion

As you can see the major features from TrueUpdate 1.0 will convert into TrueUpdate 3.0 properly, leaving you with a working version of your project. However there are some features that do not convert exactly, or do not convert at all, so it is important to fully test your project to ensure that it is working properly.


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 TrueUpdate's Registry actions. Only the sub keys will be recreated, not their values.

Values only

Recreate the values of the selected Registry key using TrueUpdate's Registry actions.

Sub keys and values

Recreate both the values and sub keys of the selected Registry key using TrueUpdate's Registry actions.

Recurse sub keys

Recurse all of the sub keys of the selected Registry key when importing the selected Registry key.


Application.Exit Examples

Application.Exit

Application.Exit (

number ReturnCode = 0 )

Example 1

Application.Exit();

Immediately exits the update.

Example 2

Application.Exit(4);

Immediately exits the update 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 update
if nChoice == 6 then
Application.Exit();
end

Confirm with the user that they wish to exit. If the choice is confirmed, exit the update, 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.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("%SourceFolder%\\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 source directory (%SourceFolder%). If the action fails, the error code message is displayed in a dialog message.

Note: In order to expand the session variable %SourceFolder% 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 update file.
File.Run(SessionVar.Expand("%SourceFolder%\\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.GetUpdateLanguage Examples

Application.GetUpdateLanguage

table Application.GetUpdateLanguage (

)

Example 1

tUpdateLanguage = Application.GetUpdateLanguage();

Retrieves the primary and secondary update language, and stores this information in a table called "tUpdateLanguage". This information can be accessed by referencing tUpdateLanguage.Primary and tUpdateLanguage.Secondary.

Example 2

-- Retrieve the update Language
tUpdateLanguage = Application.GetUpdateLanguage();

-- Check if the update language is english (English = 9)
if tUpdateLanguage.Primary == 9 then
-- Update language is english
Dialog.Message("Update Language", "Your update language is English!");
else
-- Update language is not english
Dialog.Message("Update Language", "Your update language is not English!");
end

Retrieves the update language, compares the primary ID to the value representing English (9), and displays an appropriate message.


Application.GetWndHandle Examples

Application.GetWndHandle

number Application.GetWndHandle (

)

Example 1

handle = Application.GetWndHandle();

Gets the numeric window handle for the update window and stores it in the variable "handle."

Example 2

-- Get the update window handle.
handle = Application.GetWndHandle();

-- Hide the update window.
Window.Hide(handle);

-- Sleep for 3 seconds.
Application.Sleep(3000);

-- Show the update window.
Window.Show(handle);

Gets the numeric window handle for the update 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("%SourceFolder%\\Clipboard.lmd"));

Loads the "Clipboard" action plugin into the current update.

Example 2

Application.LoadActionPlugin(Plugin_To_Load);

Loads the action plugin referenced in the variable "Plugin_To_Load" into the current update.


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 update 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 update's window to the task bar.


Application.Restore Examples

Application.Restore

Application.Restore (

)

Example 1

Application.Restore();

Restores the update'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 update 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.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.SetUpdateLanguage Examples

Application.SetUpdateLanguage

Application.SetUpdateLanguage (

number Primary,

number Secondary )

Example 1

Application.SetUpdateLanguage(0,2);

Sets the update language to the user's system default language.


Application.Sleep Examples

Application.Sleep

Application.Sleep (

number Time )

Example 1

Application.Sleep(1000);

Makes the update sleep for 1 second.

Example 2

Application.Sleep(5200);

Makes the update sleep for 5.2 seconds.


Crypto.Base64DecodeFromFile Examples

Crypto.Base64DecodeFromFile

Crypto.Base64DecodeFromFile (

string Source,

string Destination )

Example 1

-- Decodes a base64-encoded text file located in the the user's Temp folder and stores the result as a binary file.
-- The base-64-encoded text file was previously encoded using the Crypto.Base64EncodeToFile action.
Crypto.Base64DecodeFromFile(_TempFolder .."\\myfile_encoded.txt", _TempFolder .."\\myfile_decoded.txt");

-- Check to see if an error occurred in the Crypto.Base64DecodeFromFile action.
-- If an error occurred, display the error message.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Decodes a base64-encoded text file located in the user's Temp folder and stores the result as a binary file.


Crypto.Base64DecodeFromString Examples

Crypto.Base64DecodeFromString

Crypto.Base64DecodeFromString (

string Text,

string Filename )

Example 1

-- base64-encodes a small binary file and store the result in encoded_string
encoded_string = Crypto.Base64EncodeToString("C:\\myfile.exe");

-- Check to see if an error occurred using the Crypto.Base64EncodeToString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Display the contents of the string, just to show you what it looks like.
Dialog.Message("This is what the encoded string looks like:", encoded_string);

-- Decode the base64-encoded string and store the result as a binary file.
Crypto.Base64DecodeFromString(encoded_string, _TempFolder.."\\myfile_decoded_string.txt");

-- Check to see if an error occurred using the Crypto.Base64DecodeFromString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Base64 encodes a binary file and stores the result in a string. The string is then decoded and shown in a dialog message.


Crypto.Base64EncodeToFile Examples

Crypto.Base64EncodeToFile

Crypto.Base64EncodeToFile (

string Source,

string Destination,

number LineLen = 76 )

Example 1

-- Takes a binary file located in the user's Temp folder and stores the result as a base64-encoded text file,
-- also located in the user's Temp folder.
-- This file can then be decoded using the Crypto.Base64DecodeFromFile action.
Crypto.Base64EncodeToFile(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_encoded.txt");

-- Check to see if an error occurred in the Crypto.Base64EncodeToFile action.
-- If an error occurred, display the error message.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Takes a binary file located in the user's Temp folder and stores the result as a base64-encoded text file, also located in the user's Temp folder.


Crypto.Base64EncodeToString Examples

Crypto.Base64EncodeToString

string Crypto.Base64EncodeToString (

string Source,

number LineLen = 76 )

Example 1

-- Returns the contents of a small binary file as a base64-encoded string.
encoded_string = Crypto.Base64EncodeToString("C:\\MyFolder\\myfile.txt");

-- Check to see if an error occurred using the Crypto.Base64EncodeToString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end
-- Display the contents of the string, just to show you what it looks like.
Dialog.Message("This is what the encoded string looks like:", encoded_string);

-- Decode the base64-encoded string and store the result as a binary file.
Crypto.Base64DecodeFromString(encoded_string, _TempFolder.."\\myfile_decoded_string.txt");

-- Check to see if an error occurred using the Crypto.Base64DecodeFromString action.
error = Application.GetLastError();
if (error ~=0) then
result = Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

Encodes the contents of a small binary file as a base64-encoded string and shows what it looks like using a dialog message. The string is then decoded to a text file in the user's temp folder.


Crypto.BlowfishDecrypt Examples

Crypto.BlowfishDecrypt

Crypto.BlowfishDecrypt (

string Source,

string Destination,

string Key )

Example 1

-- Create a blowfish-encrypted copy of a text file in the user's temp folder
Crypto.BlowfishEncrypt(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_blowfished.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishEncrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Decrypts the blowfish-encrypted file.
Crypto.BlowfishDecrypt(_TempFolder.."\\myfile_blowfished.txt", _TempFolder.."\\myfile_blowfish_decrypted.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishDecrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Open the decrypted file to see its contents.
File.Open(_TempFolder.."\\myfile_blowfish_decrypted.txt");

Creates a blowfish-encrypted copy of a text file in the user's temp folder and then decrypts and opens the file.


Crypto.BlowfishDecryptString Examples

Crypto.BlowfishDecryptString

string Crypto.BlowfishDecryptString (

string Text,

string Key )

Example 1

sDecryptedString = Crypto.BlowfishDecryptString(sEncryptedString, sKey);

Decrypts the string 'sEncryptedString' using the key stored in 'sKey' and stores the decrypted string in the variable 'sDecryptedString'.

Example 2

-- Initialize Registration/Access variables
bRegistrationRequired = true;
bAllowAccess = false;

-- Initialize registry action variables
nMainKey = HKEY_CURRENT_USER;
sSubKey = "SOFTWARE\\Your_Product\\Registration";
sUserNameValue = "UserName";
sSerialValue = "Serial";
sMD5CheckValue = "CheckKey";
sRegisterKeyValue = "RegKey";
bAutoExpand = true;

-- if the user's registration info was stored in the Windows Registry
-- (in the form of blowfish-encrypted strings), decrypt it
if Registry.DoesKeyExist(nMainKey, sSubKey) then
-- Key exists, pull values from registry
sUserName = Registry.GetValue(nMainKey, sSubKey, sUserNameValue, bAutoExpand);
sSerial = Registry.GetValue(nMainKey, sSubKey, sSerialValue, bAutoExpand);
sMD5Check = Registry.GetValue(nMainKey, sSubKey, sMD5CheckValue, bAutoExpand);
sRegisterKey = Registry.GetValue(nMainKey, sSubKey, sRegisterKeyValue, bAutoExpand);

if (sUserName ~= "") and (sSerial ~= "") and (sMD5Check) and (sRegisterKey ~= "") then
-- All four values are present, perform check
sUserNameDecrypted = Crypto.BlowfishDecryptString(sUserName, sRegisterKey);
sSerialDecrypted = Crypto.BlowfishDecryptString(sSerial, sRegisterKey);

if (Crypto.MD5DigestFromString(sUserNameDecrypted) .. Crypto.MD5DigestFromString(sSerialDecrypted)) == sMD5Check then
-- MD5 check passed, we don't need to register
bRegistrationRequired = false;
-- allow access
bAccessAllowed = true;
end
end
end

if bRegistrationRequired then
-- Registration is required
sUserName = Dialog.Input("UserName", "Please enter your username:");
if sUserName ~= "CANCEL" and sUserName ~= "" then
-- User didn't press cancel, get serial
sSerial = Dialog.Input("UserName", "Please enter your serial number:");

if sSerial ~= "CANCEL" and sSerial ~= "" then
-- user didn't press cancel, continue.

-- get install date time in format JULIANsecondsMINUTEShours
sInstallDateTime = System.GetDate(DATE_FMT_JULIAN) .. System.GetTime(TIME_FMT_SEC) ..System.GetTime(TIME_FMT_MIN) .. System.GetTime(TIME_FMT_HOUR);

-- Generate HTTP Submit variables
sURL = "http://www.yourdomain.com/register_app.php"
tSubmitTable = {user = sUserName, serial = sSerial, installed = sInstallDateTime};
nMethod = SUBMITWEB_POST;
nTimeout = 20;
nPort = 80;
tAuth = nil;
tProxy = nil;

-- Submit to web (structure of returned string: UserNameMD5SerialMD5::Key)
sReturnedData = HTTP.Submit(sURL, tSubmitTable, nMethod, nTimeout, nPort, tAuthData, tProxyData);

if sReturnedData == "-1" or sReturnedData == "" then
-- An error occured, deny access
bAccessAllowed = false;
else
-- No error occured, cut apart string
nDelimiterPosition = String.Find(sReturnedData, "::", 1, false);
-- Get everything before the ::
sMD5Check = String.Mid(sReturnedData, 1, nDelimiterPosition - 1);

-- Get everything after the ::
sKey = String.Mid(sReturnedData, nDelimiterPosition + 2, -1);

-- Assign the registry values
Registry.SetValue(nMainKey, sSubKey, sUserNameValue, Crypto.BlowfishEncryptString(sUserName, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sSerialValue, Crypto.BlowfishEncryptString(sSerial, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sMD5CheckValue, sMD5Check, REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sRegisterKeyValue, sKey, REG_SZ);

-- set register variable to false (so the user isn't prompted to enter info again)
bRegistrationRequired = false;
-- display thank-you message
Dialog.Message("SUCCESS!", "Thank-you for registering. Enjoy the product!");

-- allow access
bAccessAllowed = true;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
end

if not bAccessAllowed then
Dialog.Message("ERROR", "Invalid registration information provided.", MB_OK, MB_ICONSTOP);
Application.Exit();
end

Reads information from the registry and decrypts it. If the information does not exist, the above script will interact with a web-based php script (http://www.yourdomain.com/register_app.php) to verify a serial number. For this example, the following php script will function:

<?
// Check for post data
if ($_POST)
{
// Initialize user array in format "Username"=>"Serial"
$user_array = array(
"John Doe"=>"abc-def-ghi",
"Jane Smith"=>"123-456-789"
);

// Get info from post variables
$user = $_POST['user'];
$serial = $_POST['serial'];
$installed = $_POST['installed'];

// Step through the user array
foreach($user_array as $username=>$serialnumber)
{
// Compare current item to the posted information
if(($user==$username) AND ($serial==$serialnumber))
{
// The current user matched, return info and exit
echo md5($user).md5($serial).'::'.$installed;
exit;
}
}

// If this script makes it this far, nothing matched, return error code
echo -1;
}
else
{
// no post data was sent, return error code
echo -1;
}
?>

Note: The above php script must be hosted on a PHP-enabled web host, and be called from your application using either an HTTP.Submit or an HTTP.SubmitSecure action.


Crypto.BlowfishEncrypt Examples

Crypto.BlowfishEncrypt

Crypto.BlowfishEncrypt (

string Source,

string Destination,

string Key )

Example 1

-- Create a blowfish-encrypted copy of a text file in the user's temp folder
Crypto.BlowfishEncrypt(_TempFolder.."\\myfile.txt", _TempFolder.."\\myfile_blowfished.txt", "trustno1withthispassword");

-- Check if any errors occurred from calling the Crypto.BlowfishEncrypt action.
-- If an error occurred, display it's error message in a dialog message.
error = Application.GetLastError();
if (error ~=0) then
Dialog.Message("Error", _tblErrorMessages[error] , MB_OK, MB_ICONEXCLAMATION, MB_DEFBUTTON1);
end

-- Open the encrypted file to see its contents.
File.Open(_TempFolder.."\\myfile_blowfished.txt");

Creates a blowfish-encrypted copy of a text file in the user's temp folder and then opens that file in the user's default text editor.


Crypto.BlowfishEncryptString Examples

Crypto.BlowfishEncryptString

string Crypto.BlowfishEncryptString (

string Text,

string Key,

number LineLen = 0 )

Example 1

sEncryptedString = Crypto.BlowfishEncryptString(sTextToEncrypt, sSecretKey);

Encrypts the text stored in 'sTextToEncrypt' with the key stored in 'sSecretKey', and stores the result in 'sEncryptedString'.

Example 2

-- Initialize Registration/Access variables
bRegistrationRequired = true;
bAllowAccess = false;

-- Initialize registry action variables
nMainKey = HKEY_CURRENT_USER;
sSubKey = "SOFTWARE\\Your_Product\\Registration";
sUserNameValue = "UserName";
sSerialValue = "Serial";
sMD5CheckValue = "CheckKey";
sRegisterKeyValue = "RegKey";
bAutoExpand = true;

-- if the user's registration info was stored in the Windows Registry
-- (in the form of blowfish-encrypted strings), decrypt it
if Registry.DoesKeyExist(nMainKey, sSubKey) then
-- Key exists, pull values from registry
sUserName = Registry.GetValue(nMainKey, sSubKey, sUserNameValue, bAutoExpand);
sSerial = Registry.GetValue(nMainKey, sSubKey, sSerialValue, bAutoExpand);
sMD5Check = Registry.GetValue(nMainKey, sSubKey, sMD5CheckValue, bAutoExpand);
sRegisterKey = Registry.GetValue(nMainKey, sSubKey, sRegisterKeyValue, bAutoExpand);

if (sUserName ~= "") and (sSerial ~= "") and (sMD5Check) and (sRegisterKey ~= "") then
-- All four values are present, perform check
sUserNameDecrypted = Crypto.BlowfishDecryptString(sUserName, sRegisterKey);
sSerialDecrypted = Crypto.BlowfishDecryptString(sSerial, sRegisterKey);

if (Crypto.MD5DigestFromString(sUserNameDecrypted) .. Crypto.MD5DigestFromString(sSerialDecrypted)) == sMD5Check then
-- MD5 check passed, we don't need to register
bRegistrationRequired = false;
-- allow access
bAccessAllowed = true;
end
end
end

if bRegistrationRequired then
-- Registration is required
sUserName = Dialog.Input("UserName", "Please enter your username:");
if sUserName ~= "CANCEL" and sUserName ~= "" then
-- User didn't press cancel, get serial
sSerial = Dialog.Input("UserName", "Please enter your serial number:");

if sSerial ~= "CANCEL" and sSerial ~= "" then
-- user didn't press cancel, continue.

-- get install date time in format JULIANsecondsMINUTEShours
sInstallDateTime = System.GetDate(DATE_FMT_JULIAN) .. System.GetTime(TIME_FMT_SEC) ..System.GetTime(TIME_FMT_MIN) .. System.GetTime(TIME_FMT_HOUR);

-- Generate HTTP Submit variables
sURL = "http://www.yourdomain.com/register_app.php"
tSubmitTable = {user = sUserName, serial = sSerial, installed = sInstallDateTime};
nMethod = SUBMITWEB_POST;
nTimeout = 20;
nPort = 80;
tAuth = nil;
tProxy = nil;

-- Submit to web (structure of returned string: UserNameMD5SerialMD5::Key)
sReturnedData = HTTP.Submit(sURL, tSubmitTable, nMethod, nTimeout, nPort, tAuthData, tProxyData);

if sReturnedData == "-1" or sReturnedData == "" then
-- An error occured, deny access
bAccessAllowed = false;
else
-- No error occured, cut apart string
nDelimiterPosition = String.Find(sReturnedData, "::", 1, false);
-- Get everything before the ::
sMD5Check = String.Mid(sReturnedData, 1, nDelimiterPosition - 1);

-- Get everything after the ::
sKey = String.Mid(sReturnedData, nDelimiterPosition + 2, -1);

-- Assign the registry values
Registry.SetValue(nMainKey, sSubKey, sUserNameValue, Crypto.BlowfishEncryptString(sUserName, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sSerialValue, Crypto.BlowfishEncryptString(sSerial, sKey), REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sMD5CheckValue, sMD5Check, REG_SZ);
Registry.SetValue(nMainKey, sSubKey, sRegisterKeyValue, sKey, REG_SZ);

-- set register variable to false (so the user isn't prompted to enter info again)
bRegistrationRequired = false;
-- display thank-you message
Dialog.Message("SUCCESS!", "Thank-you for registering. Enjoy the product!");

-- allow access
bAccessAllowed = true;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
else
-- Cancel was pressed, deny access
bAccessAllowed = false;
end
end

if not bAccessAllowed then
Dialog.Message("ERROR", "Invalid registration information provided.", MB_OK, MB_ICONSTOP);
Application.Exit();
end

Reads information from the registry and decrypts it. If the information does not exist, the above script will interact with a web-based php script (http://www.yourdomain.com/register_app.php) to verify a serial number. For this example, the following php script will function:

<?
// Check for post data
if ($_POST)
{
// Initialize user array in format "Username"=>"Serial"
$user_array = array(
"John Doe"=>"abc-def-ghi",
"Jane Smith"=>"123-456-789"
);

// Get info from post variables
$user = $_POST['user'];
$serial = $_POST['serial'];
$installed = $_POST['installed'];

// Step through the user array
foreach($user_array as $username=>$serialnumber)
{
// Compare current item to the posted information
if(($user==$username) AND ($serial==$serialnumber))
{
// The current user matched, return info and exit
echo md5($user).md5($serial).'::'.$installed;
exit;
}
}

// If this script makes it this far, nothing matched, return error code
echo -1;
}
else
{
// no post data was sent, return error code
echo -1;
}
?>

Note: The above php script must be hosted on a PHP-enabled web host, and be called from your application using either an HTTP.Submit or an HTTP.SubmitSecure action.


Crypto.MD5DigestFromFile Examples

Crypto.MD5DigestFromFile

string Crypto.MD5DigestFromFile (

string Filename )

Example 1

-- calculate the MD5 message digest for a file
-- note: edit this path so it points to an actual file :)
file = "C:\\MyFolder\\MyFile.htm";
strMD5 = Crypto.MD5DigestFromFile(file);

if (strMD5 ~= "") then
Dialog.Message("MD5DigestFromFile","The MD5 digest for "..file.." is:\r\n\r\n"..strMD5);
else
err = Application.GetLastError();
Dialog.Message("Arooga! Arooga!","ERROR "..err..": ".._tblErrorMessages[err]);
end

Calculates the MD5 message digest for a file and shows the result in a dialog message.


Crypto.MD5DigestFromString Examples

Crypto.MD5DigestFromString

string Crypto.MD5DigestFromString (

string Text )

Example 1

-- Calculate the MD5 message digest for the user's name and display it in a message
strName = Dialog.Input("", "What is your name?", "", MB_ICONQUESTION);
strDigitalSignature = Crypto.MD5DigestFromString(strName);
Dialog.Message("The digital signature for your name is:",strDigitalSignature);

Prompts for the user's name and then generates the MD5 message digest for it and shows it in a dialog message.

Example 2

--[[ note: our app allows the user to password-protect it. If the user
chose to enable password-protection, they were prompted for
a password, we appended a suffix to it (to help prevent
dictionary attacks), and the MD5 digest for the resulting
password + suffix was stored in the Registry.]]

--[[ get the digest that was stored in the Registry at HKEY_CURRENT_USER\Software\SuperDooperApp
note: this was calculated when the user supplied the password,
before it was stored ]]
reg_md5 = Registry.GetValue(HKEY_CURRENT_USER, "Software\\SuperDooperApp", "password")
-- the value only exists when the app is password-protected
if reg_md5 ~= "" then
--[[ ask the user for the password they supplied when they enabled
the password protection feature ]]
pw = Dialog.Input("", "Please enter your password:");
--[[ we added "!$" to their password before it was stored,
to help make the user's password safe from dictionary attacks ]]
pw = pw .. "!$"
-- calculate the MD5 message digest for the password + suffix
pw_md5 = Crypto.MD5DigestFromString(pw);
-- exit the app if the password digests don't match
if pw_md5 ~= reg_md5 then
Dialog.Message("", "Sorry, invalid password!");
Application.Exit();
end
end

Given that the MD5 message digest for a password was previously stored in the Registry, a user is prompted for the password and it is compared to the current password input from the user. If the message digests do not match, the application exits.


Crypto.Rot13 Examples

Crypto.Rot13

string Crypto.Rot13 (

string Text )

Example 1

-- encrypt the user's name
strName = Dialog.Input("", "What is your name?", "", MB_ICONQUESTION);

-- rot13 encrypt the name
strEncrypted = Crypto.Rot13(strName);
Dialog.Message("Your name, rot13 encrypted:",strEncrypted);

-- rot13 decrypt the name
strDecrypted = Crypto.Rot13(strEncrypted);
Dialog.Message("And now rot13 decrypted:",strDecrypted);

Encrypts a user name using "rot13", displays it in a dialog message, then rot13 decrypts it and displays it in a dialog message.


Debug.Clear Examples

Debug.Clear

Debug.Clear (

)

Example 1

Debug.Clear();

Clears the contents of the debug window.

Example 2

-- Show the debug window.
Debug.ShowWindow(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print("6 + 2 = "..total.."\r\n");

-- Ask if the debug window should be cleared.
result = Dialog.Message("Question", "Do you want to clear the debug window?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- If the user clicks the Yes button, clear the debug window.
-- If the user clicks the No button, leave it.
if result == IDYES then
Debug.Clear();
end

Outputs some text to the debug window and asks if the window should be cleared using a Dialog.Message action. If they click yes, the debug window will be cleared. If they click no, no action will be taken.


Debug.GetEventContext Examples

Debug.GetEventContext

string Debug.GetEventContext (

)

Example 1

context = Debug.GetEventContext();

Gets the current device context string and stores it in a variable named "context." For example, "Welcome > On Next"

Example 2

errmsg = "Error #" .. Application.GetLastError().. " in " .. Debug.GetEventContext();

Uses the concatenation operator (..) to form an error message containing the last error code and the current event context and stores the error message in a variable named "errmsg."

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Get the event context and print it to the debug window.
context = Debug.GetEventContext();
Debug.Print(context);

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.GetTraceMode Examples

Debug.GetTraceMode

boolean Debug.GetTraceMode (

)

Example 1

trace_mode = Debug.GetTraceMode();

Stores the current trace mode (true/false) in a variable named "trace_mode."

Example 2

if Debug.GetTraceMode() then Dialog.Message("", "Trace mode is on!") end

Displays a dialog message saying "Trace mode is on!" if trace mode is currently enabled.

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Get the event context and print it to the debug window.
context = Debug.GetEventContext();
Debug.Print(context);

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.Print Examples

Debug.Print

Debug.Print (

string Text )

Example 1

Debug.Print("Help button clicked");

Prints "Help button clicked" to the debug window. (You could put this action in the "On Help" event for a Help button to find out if the event's actions are being performed.)

Example 2

Debug.Print("On Next event fired: " .. Debug.GetEventContext());

Prints a debug message consisting of the string "On Next event fired: " followed by the current event context.

Example 3

-- Show the debug window.
Debug.ShowWindow(true);

-- Turn on the debug trace mode.
Debug.SetTraceMode(true);

-- Print some example text to the debug window.
Debug.Print("This is a test line that will be printed.\r\n");

-- Perform some addition and write it out to the debug window.
total = 6 + 2;
Debug.Print(total.."\r\n");

-- Print the current date to the debug window.
Debug.Print(System.GetDate(DATE_FMT_ISO).."\r\n");

-- Get the event context and print it to the debug window.
context = Debug.GetEventContext();
Debug.Print(context);

-- Determine if trace mode is turned on and print the result to the debug window.
trace_mode = Debug.GetTraceMode();
if trace_mode then
Debug.Print("Trace mode is on.\r\n");
else
Debug.Print("Trace mode is off.\r\n");
end

This example uses a few of the debug actions to output content to the debug window.


Debug.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 update.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("%TempFolder%\\indigorose_32bpp.png"), 5, false);

Displays the primer image file 'indigorose_32bpp.png' for five seconds before the update 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 update's window handle.
handle = Application.GetWndHandle();

-- Hide the update 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 update window.
Window.Show(handle);

Hides the update window while displaying a timed dialog message. Once the timed dialog has elapsed, the update 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.updatedate(nControlID, false);

for count = 1, 10 do
index = DlgListBox.AddItem(nControlID, "Added Item " .. count);
end

DlgListBox.updatedate(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.updatedate(nControlID, false);

for count = 1, 10 do
item_number = DlgListBox.InsertItem(nControlID, -1, "Inserted Item " .. count);
end

DlgListBox.updatedate(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 update is currently running from.

Note: _SourceDrive is a built-in variable that contains the drive letter where the update.exe file is located.

Example 2

Drive.Eject(_SourceFolder);

Ejects the CD/DVD-ROM drive the update is currently running from.

Note: _SourceFolder is a built-in variable that contains the path to the folder where the update.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 update 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 update.exe file is located.

Example 4

-- Get the type of the drive where the update 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 update 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 update.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 update 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 update, 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 update 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 update 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 update.exe file is located.

Example 3

-- Get the type of the drive where the update 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 update 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 update.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 update.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 update.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.."\\Tempupdate\\*.txt");

Deletes all of the text files in the "Tempupdate" folder located in the user's Temporary folder, and does not go into any subfolders inside "Tempupdate" 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 .. "\\update.log", false, false, true, CB_Delete);

Deletes a file named "update.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 update 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.."\\TrueUpdate 3.0\\TrueUpdate.exe");

Stores all of the attributes of the file named "TrueUpdate.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 .. "\\update.exe");

Gets the CRC value of the file "update.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/update.exe", _TempFolder.."\\update.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.."\\update.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.."\\update.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 .tu2.
viewer_path = File.GetDefaultViewer(".tu2");

-- If there is no program association for .tu2, 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 .tu2 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 .tu2 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\\TrueUpdate 3.0\\TrueUpdate.exe");

Gets the "8.3" version of the file path "C:\Program Files\TrueUpdate 3.0\TrueUpdate.exe" and stores it in the variable "short_version." The result will look similar to "C:\PROGRA~1\TRUEUP~3.0\TRUEUP~1.EXE."


File.GetSize Examples

File.GetSize

number File.GetSize (

string Filename )

Example 1

file_size = File.GetSize(_TempFolder .. "\\update.exe");

Gets the size (in bytes) of the file "update.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 .. "\\update.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 "update.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 update.exe is run from.


File.Install Examples

File.Install

boolean File.Install (

string Filename,

string Destination,

number Overwrite = 0,

boolean CreateBackup = false,

boolean SharedSystem = false,

function ProgressCallbackFunction = nil,

function OverwriteCallbackFunction = nil )

Example 1

-- Install the file cooltoy.dll.
success = File.Install(_TempFolder.."\\cooltoy.dll", _SystemFolder.."\\cooltoy.dll", FILE_INSTALL_ALWAYS, false, false, nil, nil );

-- Check to see if the install action was successful by getting an error code.
error = Application.GetLastError();

-- If the install was not successful, display it's error message.
if success == false then
Dialog.Message("Error", _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
end

Installs the "cooltoy.dll" file to the user's System folder, overwriting any existing cooltoy.dll file that might be there. Stores true or false in a variable named "success" according to whether or not the file was successfully installed. If it failed, the error code message is shown in a dialog message.


File.IsInUse Examples

File.IsInUse

boolean File.IsInUse (

string Filename )

Example 1

are_ya_busy = File.IsInUse(_WindowsFolder.."\\targetfile.exe");

Stores true in a variable named "are_ya_busy" if the "targetfile.exe" file is in use in the user's Windows directory.

Note: _WindowsFolder is a built-in variable that contains the path to the user's Windows directory.

Example 2

-- Checks to see if a particular file exists.
are_ya_there = File.DoesExist(_WindowsFolder.."\\targetfile.exe");

-- If the file exists, check to see if the file is in use.
if (are_ya_there) then
are_ya_busy = File.IsInUse(_WindowsFolder.."\\targetfile.exe");

-- If the file isn't in use, overwrite the file.
if (are_ya_busy == false) then
File.Copy(_TempFolder.."\\targetfile.exe", _WindowsFolder.."\\targetfile.exe", false, true, false, true, nil);

-- If the file is in use, notify the user.
else
result = Dialog.Message("Notice", "The specified file could not be overwritten.", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
end
end

This example first checks to see if a file called "targetfile.exe" exists. If it exists, a check is performed using the File.IsInUse action to determine if the file is in use. If it isn't in use, another file of the same name is copied over it. If it is in use, a dialog message is shown to notify the user.


File.Move Examples

File.Move

File.Move (

string Source,

string Destination,

boolean Recurse = true,

boolean Overwrite = true,

boolean AbortOnFail = false,

boolean IncludeHiddenFiles = true,

function CallbackFunction = nil )

Example 1

File.Move(_TempFolder.."\\Text Files\\*.txt", _TempFolder .. "\\Text Files Backup", false);

Moves all of the text files in the "Text Files" folder into a folder called "Text Files Backup" inside the user's temp folder, and does not go into any subfolders inside "Text Files" as it searches for files to move.

Example 2

File.Move(_SourceFolder .. "\\hidden.dat", _TempFolder .. "\\z3j2rlk\\sneaky.exe", false, true, false, true, CB_Move);

Moves a file named "hidden.dat" from the folder where the update.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 update.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 .. "\\update.exe", "C:\\update.exe");

On the next system reboot the file "update.exe" located in the user's temporary directory will be moved to "C:\update.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("%SourceFolder%\\chapter3.rtf"), "", SW_MAXIMIZE);

Opens "chapter3.rtf" located in the user's source 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 %SourceFolder% 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 update.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("%SourceFolder%\\catalogue.pdf"));

Prints the file "catalogue.pdf" located in the source folder with the user's default viewer for PDF files (probably Acrobat).

Note: In order to expand the session variable %SourceFolder% 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.."\\update.exe", "/w", "", SW_MAXIMIZE, true);

Runs "update.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 update.exe to exit before continuing with the next action. Any code returned by "update.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 update.exe file is located.

Example 3

-- Confirm that the update executable should be launched.
result = Dialog.Message("Confirm", "Are you sure you would like to update now?", MB_YESNO, MB_ICONINFORMATION, MB_DEFBUTTON1);

-- If the user clicked the Yes button.
if (result == IDYES) then

-- Run the update file.
File.Run(_TempFolder.."\\Second_update\\update.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 update file. If they click the Yes button, the update 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
UpdateDir = SessionVar.Expand("%SourceFolder%");

-- Run the file using the AppDir variable
File.Run(UpdateDir.."\\Myfile.exe", "", "", SW_SHOWNORMAL, false);

-- This could also be done as such
File.Run(SessionVar.Expand("%SoureFolder%").."\\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 update'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 .. "\\update.exe", "/W");

On the next system reboot the file "update.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..\\TrueUpdate 3.0");

Checks to see if the folder "TrueUpdate 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 "\TrueUpdate 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 update 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 update 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 update's "current directory" (working directory) to be the "Data" directory located within the user's system Temporary directory.


FTPWI.Download Examples

FTPWI.Download

FTPWI.Download (

string URL,

string Filename,

string Username = "anonymous",

string Password = "guest@",

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 21,

boolean PassiveMode = true,

function CallbackFunction = nil )

Example 1

FTPWI.Download("ftp://ftp.yourdomain.com/file.exe", _TempFolder .. "\\file.exe", "FTP_USERNAME", "FTP_PASSWORD", MODE_BINARY, 20, 21, true, nil);

err = Application.GetLastError();

if err ~= 0 then
Dialog.Message(err, _tblErrorMessages[err]);
end

Downloads 'file.exe' from an ftp site. An error message is displayed if an error occurs.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.

Example 2

function FTPCallback(BytesRead, FileSize, TransferRate, SecondsLeft, SecondsLeftFormat, Message)
Debug.Clear();
Debug.Print(
"BytesRead: " .. BytesRead .. "\r\n" ..
"FileSize: " .. FileSize .. "\r\n" ..
"TransferRate: " .. TransferRate .. "\r\n" ..
"SecondsLeft: " .. SecondsLeft .. "\r\n" ..
"SecondsLeftFormat: " .. SecondsLeftFormat .. "\r\n" ..
"Message: " .. Message .. "\r\n"
)

return true;
end

Debug.ShowWindow();
FTPWI.Download("ftp://ftp.yourdomain.com/file.exe", _TempFolder .. "\\file.exe", "FTP_USERNAME", "FTP_PASSWORD", MODE_BINARY, 20, 21, true, FTPCallback);
err = Application.GetLastError();
Debug.ShowWindow(false);

if err ~= 0 then
Dialog.Message(err, _tblErrorMessages[err]);
end

Downloads 'file.exe' from an FTP site. An error message is displayed if an error occurs. In the above example, the callback function 'FTPCallback' is used to display download information in the debug window.

Note: _TempFolder is a built-in variable that contains the path to the user's system "Temp" folder.


FTPWI.GetErrorInfo Examples

FTPWI.GetErrorInfo

table FTPWI.GetErrorInfo (

)

Example 1

ErrInfo = FTPWI.GetErrorInfo();

Gets the last FTP error info and stores it in table ErrInfo.

Example 2

FTPWI.Download("ftp://ftp.yourdomain.com/file.exe", _TempFolder .. "\\file.exe", "FTP_USERNAME", "FTP_PASSWORD", MODE_BINARY, 20, 21, true, nil);

err = Application.GetLastError();

if err ~= 0 then
FTP_Error = FTPWI.GetErrorInfo();
Dialog.Message("FTP error", FTP_Error.Number, FTP_Error.Message);
end

Downloads a file. If the returned error is anything other than successful, display the extended FTP error information.


FTPWI.GetFileSize Examples

FTPWI.GetFileSize

number FTPWI.GetFileSize (

string URL,

string Username = "anonymous",

string Password = "guest@",

number Mode = MODE_BINARY,

number Timeout = 20,

number Port = 21,

boolean PassiveMode = true,

function CallbackFunction = nil )

Example 1

nFileSize = FTPWI.GetFileSize("ftp://ftp.myftpsite.com/myfile.txt", "anonymous", "guest@", MODE_BINARY, 20, 21, true, nil);

Gets the size of the file "myfile.txt" and stores the result in nFileSize.

Example 2

-- Settings for FTPWI actions
sFileOnServer = "ftp://ftp.myftpsite.com/myfile.exe";
sLocalFilePath = _TempFolder .. "\\myfile.exe";
sServerUser = "anonymous";
sServerPass = "guest@";
nServerMode = MODE_BINARY;
nServerTimeout = 20;
nServerPort = 21;
bUsePassive = true;

-- Set the max bytes allowed without alerting the user to 2MB (2*1024*1024):
QuestionByteThreshold = 2097152;

-- Assume download should continue
bContinueDownload = true;

-- Get size of file to be downloaded
FileSize = FTPWI.GetFileSize(sFileOnServer, sServerUser, sServerPass, nServerMode, nServerTimeout, nServerPort, bUsePassive, 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
FTPWI.Download(sFileOnServer, sLocalFilePath, sServerUser, sServerPass, nServerMode, nServerTimeout, nServerPort, bUsePassive, nil);
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 an FTP server to be downloaded. If the file is larger than a predefined threshold, the user is asked if the download should continue.


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/update.exe", _TempFolder.."\\update.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.."\\update.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.."\\update.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/update.exe", SessionVar.Expand("%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.


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/update.exe", _TempFolder.."\\update.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.."\\update.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.."\\update.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
TrueUpdate.WriteToLogFile("HTTP Download Error Info: " .. http_error.Number .. " - " .. http_error.Message, true);
TrueUpdate.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 TrueUpdate 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="TrueUpdate"}, SUBMITWEB_GET, 20, 80, nil, nil);

This example submits the query "TrueUpdate" 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="TrueUpdate"}, SUBMITWEB_GET, 20, 443, nil, nil);

This example submits the query "TrueUpdate" 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/update.exe", _TempFolder.."\\update.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.."\\update.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.."\\update.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 update.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", "update", "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 update.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 update.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", "update");

-- 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 update 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 update section." , MB_OK, MB_ICONINFORMATION);
end
end

Gets all of the value names within the "update" 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\\0update=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", "updatePath");

Deletes the value "updatePath" from the sub key HKEY_LOCAL_MACHINE\Software\My Application.

Example 2

Registry.DeleteValue (2, "Software\\My Application", "updatePath");

Deletes the value "updatePath" 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", "updatePath", false);

Gets the data in the "updatePath" 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", "updatePath");

Gets the type of data stored in the "updatePath" value located at "HKEY_LOCAL_MACHINE\Software\My Application" and stores the corresponding numeric constant in value_type. If the "updatePath" 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 updatePath 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", "updatePath", _ProgramFilesFolder .. "\\My Application", 1);

Sets the "updatePath" 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 in the update.


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 To Update");

Jumps to the screen named "Welcome To Update."

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


Screen.Return Examples

Screen.Return

Screen.Return (

number ReturnCode )

Example 1

Screen.Return(1);

Return a code stating that the user clicked the screen's back button.

Example 2

Screen.Return(SR_SUCCESS);

Return a code stating that the screen succeeded.


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 updateing this!");

Sets the string with id "My_String" to "Hello, thank-you for updateing this!" for the current screen.

Example 2

Screen.SetLocalizedString(sStringID, sString);

Sets the string with the id referenced in "sStringID" to the string referenced in "sString" for the current screen.


Screen.Show Examples

Screen.Show

number Screen.Show (

string ListName,

string FirstScreen = "" )

Example 1

Screen.Show("List1", "");

Shows the first screen in screen list 'List1'.

Example 2

Screen.Show("Button_Screens", "Screen_4");

Shows the screen with name 'Screen_4' from the screen list named 'Button_Screens'.


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 update which cannot be run while a virus scanner is active
File.Run(SessionVar.Expand("%SourceFolder%\\update2.exe"), "", "", SW_SHOWNORMAL, true);

-- Resume the virus scanner
Service.Continue(VirusScannerServiceName, "");

Pauses the specified virus scanner service before launching a separate update 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 update which cannot be run while a virus scanner is active
File.Run(SessionVar.Expand("%SourceFolder%\\update2.exe"), "", "", SW_SHOWNORMAL, true);

-- Resume the virus scanner
Service.Continue(VirusScannerServiceName, "");

Pauses the specified virus scanner service before launching a separate update 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

supdateMessage = SessionVar.Expand("%ProductName% v%ProductVer% update");

Stores a custom update message in a string "supdateMessage" from the session variables %ProductName% and %ProductVer%.


SessionVar.Get Examples

SessionVar.Get

string SessionVar.Get (

string VariableName )

Example 1

sMyVar = SessionVar.Get("%MyVar%");

Gets the contents of the session variable %MyVar%. If %MyVar% contains other session variables, the names of those variable will be returned, not their expanded contents.

Example 2

sResult = SessionVar.Get(sVarName);

Gets the contents of the session variable contained in "sVarName". If this variable contains other session variables, these variable names will be returned.


SessionVar.Remove Examples

SessionVar.Remove

SessionVar.Remove (

string VariableName )

Example 1

SessionVar.Remove("%UserSerialNumber%");

Undefines the session variable %UserSerialNumber%.

Example 2

sVariableName = "%Password%";
SessionVar.Remove(sVariableName);

Undefines the session variable %Password%, which is stored in the string "sVariableName."


SessionVar.Set Examples

SessionVar.Set

SessionVar.Set (

string VariableName,

string Value )

Example 1

SessionVar.Set("%ReleaseDate%", "January 1");

Sets the value of %ReleaseDate% to "January 1". If %ReleaseDate% does not exist, it is created.

Example 2

SessionVar.Set("%updateDate%", System.GetDate(DATE_FMT_JULIAN));

Sets the value of %updateDate% 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
TempDir = SessionVar.Expand("%TempFolder%");

-- Call a file using the TempDir variable
Shell.Execute(TempDir.."\\Myfile.exe", "open", "", "", SW_SHOWNORMAL);

-- This could also be done as such
Shell.Execute(SessionVar.Expand("%TempDir%").."\\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 TrueUpdate 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 TrueUpdate action or any other element of your project. An example of the dialog can be seen below:

There are several actions in TrueUpdate 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

  • FTPWI.Download

  • FTPWI.GetFileSize

  • HTTP.Download

  • HTTP.DownloadSecure

  • HTTP.GetFileSize

  • HTTP.GetFileSizeSecure

  • TrueUpdate.GetServerFile

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 TrueUpdate. 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 update 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 update?", 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 update should continue. If the system supports system restore, or the user chooses to continue, a restore point is set and the update 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 update?", 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 update should continue. If the system supports system restore, or the user chooses to continue, a restore point is set and the update 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 update.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 update.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.


TrueUpdate.GetLocalizedString Examples

TrueUpdate.GetLocalizedString

string TrueUpdate.GetLocalizedString (

string StringID )

Example 1

sLocalSuccess = TrueUpdate.GetLocalizedString("MSG_SUCCESS");

Gets the localized "success" string and stores it in string sLocalSuccess.


TrueUpdate.GetServerFile Examples

TrueUpdate.GetServerFile

boolean TrueUpdate.GetServerFile (

string ServerID,

boolean ShowRestartDialog = true,

function CallbackFunction = nil )

Example 1

bLoaded = TrueUpdate.GetServerFile("TrueUpdate Server 1", true, nil);

Gets the server configuration files from "TrueUpdate Server 1", and loads them automatically once they are downloaded.

Example 2

tUpdateServers = TrueUpdate.GetUpdateServerList();
nMaxServers = Table.Count(tUpdateServers);

bValidServer = false;
nServerNo = 1;

while (not bValidServer) do
bValidServer = TrueUpdate.GetServerFile(tUpdateServers[nServerNo], true, nil)
if (not bValidServer) then
nServerNo = nServerNo + 1;
end
if (nServerNo > nMaxServers) then
Dialog.Message("Error", "All attempts at downloading a server configuration file have failed. Update will now terminate");
Application.Exit();
end
end

Gets a list of all available TrueUpdate Servers and attempts to get the server configuration files from each one until a valid server is found. If no server can be connected to, an error is displayed, and the update exits.


TrueUpdate.GetUpdateServerList Examples

TrueUpdate.GetUpdateServerList

table TrueUpdate.GetUpdateServerList (

)

Example 1

tServers = TrueUpdate.GetUpdateServerList();

Gets a list of the TrueUpdate Servers and stores it in the table 'tServers'.

Example 2

tUpdateServers = TrueUpdate.GetUpdateServerList();
nMaxServers = Table.Count(tUpdateServers);

bValidServer = false;
nServerNo = 1;

while (not bValidServer) do
bValidServer = TrueUpdate.GetServerFile(tUpdateServers[nServerNo], true, nil)
if (not bValidServer) then
nServerNo = nServerNo + 1;
end
if (nServerNo > nMaxServers) then
Dialog.Message("Error", "All attempts at downloading a server configuration file have failed. Update will now terminate");
Application.Exit();
end
end

Gets a list of all available TrueUpdate Servers and attempts to get the server configuration files from each one until a valid server is found. If no server can be connected to, an error is displayed, and the update exits.


TrueUpdate.LoadServerFile Examples

TrueUpdate.LoadServerFile

boolean TrueUpdate.LoadServerFile (

string ServerFilePath,

string Key )

Example 1

TrueUpdate.LoadServerFile(_WindowsFolder .. "\\ProductUpdate.ts1", "C886C4C7-E1EF-40FA-9908-56FBC5744AF2");

Loads a server file from the user's windows folder.

Example 2

-- Loads the server file my_old_product.ts1, containing scripts and screens
loaded = TrueUpdate.LoadServerFile(_TempFolder .. "\\myproduct.ts1", "92481934-AA72-40C6-A390-E0F8663C9F64");

-- Runs the "Server Script" from_my_old_product.ts1
TrueUpdate.RunScript("Server Script");

-- Runs the "Custom" script from my_old_product.ts1
TrueUpdate.RunScript("Custom");

-- Loads the "Finished" screen list from my_old_product.ts1
Screen.Show("Finished", "");

-- Note: To show screens and run scripts from the server files
-- associated with the CURRENT project, you must use
-- TrueUpdate.GetServerFile action to load the current project's
-- server files before performing any actions.

Loads a server file from the user's temporary directory, runs scripts, and shows screens.

Note: To show screens and run scripts from the server files associated with the CURRENT project, you must use TrueUpdate.GetServerFile action to load the current project's server files before performing any actions.


TrueUpdate.RunScript Examples

TrueUpdate.RunScript

TrueUpdate.RunScript (

string ScriptID )

Example 1

TrueUpdate.RunScript("Server Script");

Runs the script whose name is 'Server Script'.


TrueUpdate.SetLocalizedString Examples

TrueUpdate.SetLocalizedString

TrueUpdate.SetLocalizedString (

string StringID,

string Text )

Example 1

TrueUpdate.SetLocalizedString("MSG_SUCCESS", "Whatever just happened worked!");

Sets the "Success" string of the current language to "Whatever just happened worked!".


TrueUpdate.WriteToLogFile Examples

TrueUpdate.WriteToLogFile

TrueUpdate.WriteToLogFile (

string Text,

boolean AddTimestamp = true )

Example 1

TrueUpdate.WriteToLogFile("ERROR: " .. Application.GetLastError(), true);

Outputs the current application error to the update log file.

Example 2

err = Application.GetLastError();

if err ~= 0 then
sMessage = "####################\r\n" .. "ERROR " .. err .. ": " .. _tblErrorMessages[err] .. "\r\n####################\r\n";
TrueUpdate.WriteToLogFile(sMessage, false);
end

If an error occurs, outputs a nicely-formatted string into the update 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 = "update.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", "update 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 update.exe running on the system. To accomplish this, use the Window.EnumerateProcesses action, and check every process against the filename update.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 update 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 update'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 update 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 update'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 update's window handle.
handle = Application.GetWndHandle();

-- Hide the update window.
Window.Hide(handle);

-- Sleep for 3 seconds.
Application.Sleep(3000);

-- Show the update window.
Window.Show(handle);

Gets the numeric window handle for the update 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 update's window handle.
handle = Application.GetWndHandle();

-- Hide the update's window.
Window.Hide(handle);

-- Sleep for 3 seconds.
Application.Sleep(3000);

-- Show the update'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.


Upload Location (File Copy)

Settings

Upload Location (File Copy)

Name/ID:

The unique identifier of the current upload location. This identifier is mainly used as a readable label for identifying this location.

Folder path:

The full path to the folder you would like the TrueUpdate server configuration files to be copied to (eg. C:\My Update Files\). You can click the Browse button to select a folder on your system.


Upload Location (FTP)

Settings

Upload Location (FTP)

Name/ID:

The unique identifier of the current upload location. This identifier is mainly used as a readable label for identifying this location.

Folder address:

The full address of the FTP site, including the directory, that you want to upload the server configuration files to (e.g. "ftp.yourdomain.com/trueupdate/").

Note: The protocol designator is optional, e.g. "ftp.yourdomain.com/trueupdate/" and "ftp://ftp.yourdomain.com/trueupdate/" are equally valid.

Test

Test the FTP settings to ensure they are correct by uploading a small file and then deleting it. A dialog will open to show the status and result of the test.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate publisher and the FTP site.

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:

The port to connect to on the FTP server. The standard FTP port 21 is used by default.

Authentication

Username:

The name to use to log into the FTP site. Enter "anonymous" or leave blank for anonymous FTP.

Password:

The password for the FTP site that goes with the FTP user name. For anonymous FTP, use your email address.

Account:

An FTP account name for servers that require it. (Some servers require a login name, password, and account name instead of just a login name and password.) VERY RARELY necessary.

Use passive mode

Use passive/firewall mode when publishing the server files. Passive mode (also known as "firewall mode") is required whenever you need to transfer files to or from an FTP server from behind a firewall.

Normally, your computer makes a connection to an FTP server, and the FTP server responds by opening a connection back to your computer. This return connection won't work if your computer can't be reached directly from the Internet. In passive mode, both connections are made from your computer, so the FTP server doesn't have to do any connecting—it just waits passively for your computer to make both of the connections to it.

Most servers support passive mode connections, so it's generally best to leave this setting enabled.


Upload Location (SFTP)

Settings

Upload Location (SFTP)

Name/ID:

The unique identifier of the current upload location. This identifier is mainly used as a readable label for identifying this location.

Folder address:

The full address of the FTP site, including the directory, that you want to upload the server configuration files to using SFTP (e.g. "ftp.yourdomain.com/trueupdate/").

Note: The protocol designator is optional, e.g. "ftp.yourdomain.com/trueupdate/" and "ftp://ftp.yourdomain.com/trueupdate/" are equally valid.

Test

Test the SFTP settings to ensure they are correct by uploading a small file and then deleting it. A dialog will open to show the status and result of the test.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate publisher and the FTP site.

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:

The port to connect to on the FTP server. The standard SFTP port 22 is used by default.

Authentication

Username:

The name to use to log into the FTP site. Enter "anonymous" or leave blank for anonymous FTP.

Password:

The password for the FTP site that goes with the FTP user name. For anonymous FTP, use your email address.

Account:

An FTP account name for servers that require it. (Some servers require a login name, password, and account name instead of just a login name and password.) VERY RARELY necessary.

Use passive mode

Use passive/firewall mode when publishing the server files. Passive mode (also known as "firewall mode") is required whenever you need to transfer files to or from an FTP server from behind a firewall.

Normally, your computer makes a connection to an FTP server, and the FTP server responds by opening a connection back to your computer. This return connection won't work if your computer can't be reached directly from the Internet. In passive mode, both connections are made from your computer, so the FTP server doesn't have to do any connecting—it just waits passively for your computer to make both of the connections to it.

Most servers support passive mode connections, so it's generally best to leave this setting enabled.


Add New Language

Overview

Adding a new language to your update means that you want the update to detect that language and use its corresponding language message file and translated screens for the update.

Available languages:

A list of the languages you can detect in your update. You can select the language you wish to support in your update 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 TrueUpdate's web site, www.trueupdate.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 Example

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:

Add the following code to the Client Script:

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


Organize Scripts

Overview

The Organize Scripts dialog allows you to organize the custom script tabs you have added to your project in order to increase your work flow. This may be useful if the number script tabs you have added extends past the viewable area of the design environment. This feature prevents you from having to scroll over to find commonly used script tabs.

Note: You can only change the order of script tabs that you have added (custom script tabs). You cannot change the order of the Client Script or Server Script tabs. You also must have at least two custom script tabs in order to use this feature.

Script tabs are ordered from left to right in the design environment in the order you have added them to your project. The first script tab in the list of this dialog will appear as the first tab on the left hand side of the design environment.

Move Up

Move the selected custom script tab up one position in the script tab list.

Move Down

Move the selected custom script tab down one position in the script tab list.


Theme Properties

Style

Colors

Use Custom

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

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.

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 TrueUpdate:

*.apm; *.bmp; *.emf; *.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.

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.


TrueUpdate Server (FTP)

Settings

An FTP TrueUpdate server location is a folder on an FTP server where the TrueUpdate client will download the server configuration files from using FTP (file transfer protocol).

Server Info

Name/ID:

The unique identifier of the current TrueUpdate server location. This identifier can be used whenever you need to access this particular server location.

Folder address:

The full address of the FTP site including the directory. The protocol designator is optional, e.g. "ftp.yourdomain.com/trueupdate/" and "ftp://ftp.yourdomain.com/trueupdate/" are equally valid.

Tip: The folder address also supports the expansion of session variables, allowing you to change it dynamically at runtime.

Timeout:

The connection timeout in seconds for communication between the TrueUpdate client and the FTP site.

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:

The port to connect to on the FTP server. The standard FTP port 21 is used by default.

Authentication

Username:

The name to use to log into the FTP site. Enter "anonymous" or leave blank for anonymous FTP.

Password:

The password for the FTP site that goes with the Username. For anonymous FTP, use your email address.

Account:

An FTP account name for servers that require it. (Some servers require a login name, password, and account name instead of just a login name and password.) VERY RARELY necessary.

Use passive mode

Use passive/firewall mode when transferring files. Passive mode (also known as "firewall mode") is required whenever you need to transfer files to or from an FTP server from behind a firewall.

Normally, your computer makes a connection to an FTP server, and the FTP server responds by opening a connection back to your computer. This return connection won't work if your computer can't be reached directly from the Internet. In passive mode, both connections are made from your computer, so the FTP server doesn't have to do any connecting—it just waits passively for your computer to make both of the connections to it.

Most servers support passive mode connections, so it's generally best to leave this setting enabled.


TrueUpdate Server (HTTP)

Settings

An HTTP TrueUpdate server location is a URL to a location on a Web server. The TrueUpdate client will download the server configuration files from the Web site using the HTTP protocol.

Server Info

Name/ID:

The unique identifier of the current TrueUpdate server location. This identifier can be used whenever you need to access this particular server location.

Folder URL:

The URL containing the directory where the TrueUpdate server configuration files will be hosted. The protocol designator is optional, e.g. "www.yourdomain.com/trueupdate/" and "http://www.yourdomain.com/trueupdate/" are equally valid.

Tip: The folder URL also supports the expansion of session variables, allowing you to change it dynamically at runtime.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate client and this HTTP site.

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:

The port to connect to on the HTTP server. The standard HTTP port 80 is used by default.

Authentication

This section allows you to specify a user name and password if the URL is protected by basic HTTP authentication.

Use authentication

Include basic HTTP authentication information in the HTTP request.

Username:

The user name to use during authentication.

Password:

The password to use during authentication.


TrueUpdate Server (HTTPS)

Settings

An HTTPS TrueUpdate server location is a URL to a location on a secure Web server. The TrueUpdate client will download the server configuration files from the Web site using the HTTP protocol exchanged over an SSL (Secure Socket Layer)-encrypted session. This is known as the "secure hypertext transfer protocol."

Note: This location requires that you have access to a secure Web server.

Server Info

Name/ID:

The unique identifier of the current TrueUpdate server location. This identifier can be used whenever you need to access this particular server location.

Folder URL:

The URL containing the directory where the TrueUpdate server configuration files will be hosted on the secure Web server. The protocol designator is optional, e.g. "www.yourdomain.com/trueupdate/" and "https://www.yourdomain.com/trueupdate/" are equally valid.

Tip: The folder URL also supports the expansion of session variables, allowing you to change it dynamically at runtime.

Timeout:

The connection timeout (in seconds) for communication between the TrueUpdate client and this HTTPS site.

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:

The port to connect to on the HTTPS enabled server. The standard HTTPS port 443 is used by default.

Authentication

This section allows you to specify a user name and password if the URL is protected by basic HTTP authentication.

Use authentication

Include basic HTTP authentication information in the HTTP request.

Username:

The user name to use during authentication.

Password:

The password to use during authentication.


TrueUpdate Server (LAN/Local)

Settings

Server Info

Name/ID:

The unique identifier of the current TrueUpdate server location. This identifier can be used whenever you need to access this particular server location.

Folder path:

The path to the folder where the TrueUpdate server configuration files will be hosted. This can be a full or UNC path to a mapped drive. You can click the Browse button to select a folder on your system.

Tip: The folder path also supports the expansion of session variables, allowing you to change it dynamically at runtime.


Progress 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:

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

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

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

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Check Box Properties

Overview

Text

Label:

The text you want to display to the right of the check box.

Note: Using the ampersand character (&) in a label's text will make the character to its right a mnemonic key for the control.

States

Enabled

Enable the check box so it responds to user interaction. When an check box is disabled, it will appear greyed out and cannot be edited.

Visible

Set the initial visibility of the check box (whether it's visible when the screen is displayed).

Default Value

Unchecked

Show the check box as unchecked when the screen displays.

Checked

Show the check box as checked when the screen displays.

Result Variable

Store state in LUA variable:

The LUA variable that you want to store the state of the check box. If the check box is checked when leaving this screen, true will be stored. If the check box is unchecked, false is stored.

Language

Language:

The supported language you want to translate the check box for. You can click the select button ( [image] ) to select a different language currently supported in your update.

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.

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

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

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

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

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

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

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

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 TrueUpdate 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 update.

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

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

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

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

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 update, 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 edit field. 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 update.

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

Note: You can add additional language support from the Languages dialog which can be accessed by going to Project > Languages...


Add to Gallery

Overview

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.


Screen Gallery

Overview

Screens:

A list of all of the available screens that can be added to the update. 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.