StaticText control

A StaticText control displays a text string, usually as a label for another control or as explanatory text in a dialog box. It can also display dynamic text strings that are linked to a symbolic variable anywhere in the project, or act as a hyperlink that opens a web page, a file, or executes installer actions when clicked.

Tip: To use a StaticText control as a label for another control, the StaticText control should precede the other control in the dialog's tab order. You can achieve this in the Dialogs tree on the Dialogs project page by moving the StaticText control to immediately above the other control.

Tip: To change the tab and Z-order of a control in a dialog box (i.e., the order in which they are drawn and how they appear "on top" of each other), select the control in the dialog/control tree in the left pane on the Dialogs project page, then use Ctrl+Up and Ctrl+Down to move the control up or down in the order. These keystrokes are shortcuts for the Move Up and Move Down commands on the control's context menu.

Dynamic text display

You can use a StaticText control to display a dynamic text string by linking it to a symbolic variable (see Symbol name). The control's text will be updated each time the variable's value changes.

Tip: You can also use a Set Window State action to set the StaticText control's text (or any other control's text).

Hyperlink controls

Tarma's StaticText controls can also be used as hyperlinks: if the user clicks on a hyperlink control, the corresponding web page is opened or one or more actions are executed.

You can create a hyperlink-type StaticText control as follows:

  1. Create the StaticText control
  2. Set its Type to Hyperlink
  3. Enter the user-visible caption text in the Caption field.
  4. Do one of the following:

    • Enter the hyperlink target in the Hyperlink field. This can be a URL (for example, https://tarma.com/ or mailto:support@tarma.com; be sure to include the appropriate protocol identifier), or a file path (for example, <WindowsFolder>\notepad.exe or <INSTALLDIR>\Readme.txt).
      --or--
    • Leave the Hyperlink field empty and assign one of the standard IDxxx control identifiers to the Control ID field; this will cause the corresponding default action to be executed when the user clicks the hyperlink.
      --or--
    • Leave the Hyperlink field empty and create an event handler for the control's OnClicked event instead. In the event handler, add whatever actions you want the installer to perform when the user clicks the hyperlink.
  5. If you want the hyperlink to appear as a hyperlink, then set its Font attribute to UnderlineFont (use ... to select the font) and set Color to Hyperlink.

Attributes

The following attributes and options are available.

Attribute Description
Control name Enter the internal name for the control. This name is for use in InstallMate only; it is not used in the installer. All control names must be unique within their parent dialog box.
Control ID

Select a control ID from the drop-down list or type a numerical ID to use for this control. All controls within a dialog must have different control IDs. For StaticText controls, you should generally select Automatic. However, if you want a hyperlink-type control to behave as a PushButton control (in particular, if you want InstallMate to execute the same default action), then you should select the appropriate IDxxx value.

See Dialog control IDs for an explanation of the available control IDs and their usage.

Caption type

Select the desired StaticText control behavior from the drop-down list. The following choices are available:

Type Description
Static The control behaves as a normal static text control.
Hyperlink The control behaves as a hyperlink. In particular, it will generate an OnClicked event if the users clicks on the control. Furthermore, if the Hyperlink attribute (below) is not empty, it will use the Win32 function ShellExecute to open whatever appears in the Hyperlink field.
Dynamic The control behaves as a static text control but gets its text from the symbolic variable specified by Symbol name (below). The displayed text is automatically updated whenever the variable's value changes.
Caption

Enter the text for the control's caption; any symbolic references in the Caption are resolved when the control is first displayed. If Type is set to Dynamic, this text will be replaced by the linked variable's value when the dialog is shown and updated whenever the variable's value changes (see Symbol name below).

If you want a letter to appear underlined and act as a keyboard accelerator (as in the Windows' Label: style), you should prefix the letter with an ampersand ('&'). For example, &Label will appear as Label in the dialog box.

Note: The visibility of the underline is subject to the Windows settings on the target system (and your own development system); on Windows 2000 and later, the underline only appears if you first press the Alt key.

Localized Check this box to localize the Caption field and use different captions for different languages.
Hyperlink

Enter the hyperlink target path. This can be anything that the Win32 function ShellExecute knows how to handle, including URLs such as https://tarma.com/ and mailto:support@tarma.com (be sure to include the appropriate protocol identifier), or file paths such as <WindowsFolder>\notepad.exe (an executable program) and <INSTALLDIR>\Readme.txt (a document file).

You can leave this field empty if you want to use the hyperlink-style control to execute a different action than opening a URL or file. In that case, either assign the appropriate predefined IDxxx control identifier in the Control ID field, or define an event handler for the control's OnClicked event with the desired actions.

Note: This action requires that an appropriate shell handler is registered for the protocol. This may not always be the case; for example, Core installations have very few protocol handlers registered (no http: handler, for example).

Format

Select the desired format for the dynamic control text from the drop-down list. The following choices are available:

Format Description
None Displays the variable's value as-is.
KBytes Interpret the value as a number of bytes and format them as KB (1 KB = 1024 bytes) with a KB suffix (this suffix is localized using string #00078 on the Messages page). This is useful to display information such as available disk space (PrimaryVolumeSpaceAvailable variable), feature installation size (TsuFeatureSize variable), file size progress (TsuProgressPos and TsuProgressRange), but can be used for any variable that represents a number of bytes.
Progress Interpret the value as the installation progress in permilles (0..1000) and format this as a percentage (0..100) with a % suffix. This is useful to display the installation progress (the TsuProgress variable), but can be used for any variable that has a numerical value in the 0..1000 range.
Ellipsis

Select the desired behavior if the control's Caption text is longer than the width of the control. The following choices are available:

Ellipsis Description
None The text will wrap to the next line if necessary. You must increase the control's height for the wrapped text to be visible.
End Truncate the text at the end and display a ... ellipsis at the end if the text is too long to fit in the control.
Path Truncate the text before the last '\' character and display a ... ellipsis instead of the removed text. This option is useful if the text represents a file or folder path, because it retains the initial and final parts of the path as far as possible.
Word Truncate the text at the end and display a ... ellipsis at the end if the text is too long to fit in the control. (This is documented as different from End ellipsis by Microsoft, but appears to have the same effect.)
No prefix Check this box to display ampersands (&) in the control's Caption text as-is; clear it to interpret them as keyboard accelerators. In the latter case, the ampersand itself is not displayed, but the character following it is underlined and acts as an Alt+character keyboard accelerator. You should check this box if you don't want this behavior.
Center vertically Check this box to center the Caption text vertically in the control; clear it to align it at the top of the control's area.
Symbol name

Enter the name of the symbolic variable to which the control must be linked, or click ... (browse) to open the Select Symbolic Variable dialog box that allows you to select a variable from the project.

The control's caption will display the value of the linked variable and will be updated automatically whenever the variable's value changes.

Indirect symbol Check this box to make the Symbol name link indirect; clear it for a direct link. If the link is indirect, the variable specified in the Symbol name field is used to obtain the name of a second variable, and it is this second variable whose value is monitored by the control. With a direct link, the variable specified by the Symbol name attribute itself is monitored.
Font Select the font style for the text in the control by clicking ... (browse) to open the Select Font Style dialog. If no font style is selected, the control uses the parent dialog's font style. You can remove the font style by clicking X (clear).
Text color

Select the desired text color from the drop-down list. The following choices are available:

Color Description
Default Use the system color for text in dialog boxes, usually black (COLOR_BTNTEXT).
Black Use the system color for text in windows, usually black (COLOR_WINDOWTEXT).
White Use the system color for text in window captions, usually white (COLOR_CAPTIONTEXT).
Hyperlink Use the color for hyperlink text; this is currently fixed at blue.
Gray Use the system color for grayed-out text, usually gray (COLOR_GRAYTEXT)
Custom... Use a custom color. Click the ... (choose color) button to open the standard Color dialog box, where you can choose the desired color.

Note: The actual display colors depend on the Windows' settings. If the user has selected a different color scheme, then the control will use the appropriate colors from that scheme.

Background

Select the desired background color from the drop-down list. The following choices are available:

Color Description
Default Use the system color for dialog box backgrounds, usually light gray (COLOR_3DFACE).
Dark gray Use the system color for shadows, usually dark gray or black (COLOR_3DSHADOW).
Light gray Use the system color for buttons, usually light gray (COLOR_BTNFACE).
White Use the system color for window backgrounds, usually white (COLOR_WINDOW).
Caption Use the system color for window captions, usually blue (COLOR_CAPTION).
CaptionEnd Use the system end color for windows captions with a color gradient, usually light blue (COLOR_GRADIENTACTIVECAPTION).
Workspace Use the system color for application workspaces, usually dark gray (COLOR_WORKSPACE).
Desktop Use the system color for the Desktop, usually blue or green (COLOR_DESKTOP).
Info Use the system color for info tip windows, usually pale yellow (COLOR_INFOBK).
Custom color... Use a custom color. Click the ... (choose color) button to open the standard Color dialog box, where you can choose the desired color.

Note: The actual display colors depend on the Windows' settings. If the user has selected a different color scheme, then the control will use the appropriate colors from that scheme.

Note: If you select Transparent, then the Background color option will be ignored.

Horizontal align

Select the desired alignment for the control's Caption text. The following choices are available:

Align Description
No wrap Text is left-aligned but does not wrap to the next line if it's wider than the control. (It will be truncated with or without ellipsis, depending on the Ellipsis setting.)
Left Left-align the text, with optional wrapping or truncation depending on the Ellipsis setting.
Center Center the text, with optional wrapping or truncation depending on the Ellipsis setting.
Right Right-align the text, with optional wrapping or truncation depending on the Ellipsis setting.
Enabled
Tab stop
Group
Border
Sunken
Client edge
Visible
Transparent
Don't mirror

These are all standard control styles; see Dialog control styles for a description.

Note: If you select Transparent, then the Background color option will be ignored.

Condition Enter the display condition for the control or leave empty to display the control unconditionally. See Dialog control conditions for more information.

Related topics

Dialogs, Working with attribute panes