User's Guide - Chapter 5: 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.
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)
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 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.
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
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
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 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.
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.
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.
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.
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.
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.
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.
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.
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 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 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 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.
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 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.
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)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.