InstallShield 2016
Project • This information applies to the following project types:
| • | InstallScript |
| • | InstallScript MSI |
InstallShield includes support for HTML controls on dialogs in InstallScript and InstallScript MSI projects. HTML controls enable you to use HTML markup for dialog controls. You can include on dialogs links to Web pages, installed HTML files, and HTML support files. If an end user clicks the hyperlink on the run-time dialog, you can have the HTML page open in an Internet browser, or you can trigger other behavior that you have defined through your InstallScript code. The HTML control lets you use any valid HTML markup, including styles to control their appearance.
The HTML control also lets you display the HTML content directly on a dialog if the content is an installed HTML file or HTML support file.
To create an HTML control, you need to start with a static text control. Once you have placed the static text control on a dialog, you can convert it to be an HTML control.
To convert any static text control on a dialog to be an HTML control, do one of the following:
| • | In the Dialogs view, set the Text property of the control as follows: |
[html] HTML Markup
| • | Use InstallScript to set the text of a control to be [html], followed by the HTML markup. |
At run time, the InstallScript engine converts the control to an HTML control.
Example
The following example demonstrates how to convert a static text control to an HTML control. The sample HTML code enables you to set the colors and fonts of the control so that they match those of the dialog.
To convert a static text control to an HTML control by using the control’s Text property:
| 1. | In the View List under User Interface, click Dialogs. |
| 2. | In the Dialogs explorer, right-click the dialog that you want to contain the HTML control, and then click Edit. InstallShield displays the dialog in the Dialog Editor, using the project’s default language. |
| 3. | Click the static text control that you want to convert to an HTML control. InstallShield displays its properties in the right pane. |
| 4. | In the Text property, click the ellipsis button (...). InstallShield displays a list of all of the current strings in the project. |
| 5. | Click the Edit button. |
| 6. | Set the value of the string identifier as follows: |
[html]<style type="text/css">html,body {padding:0; margin:0; background-color:ButtonFace} * {font-size: 8pt; font-family: "MS Sans Serif";} </style> <a href="http://www.MyWebSite.com">Visit my Web site</a>
At run time, the installation uses the default InstallScript dialog font (8 point MS Sans Serif) and sets the background color to the Windows dialog color, which is usually gray. If the content is on a dialog area that is white, you can omit the background-color:ButtonFace style part so that the background of the HTML control becomes white.
Tip • As an alternative to converting the static control through the Dialogs view, you could edit the dialog’s script function in the InstallScript view. For example, add the following code to the DLG_INIT case in the dialog message loop:
CtrlSetText( szDlg, HTML_CTRL_ID, "[html]<style type=\"text/css\">html,body {padding:0; margin:0; background-color:ButtonFace} * {font-size: 8pt; font-family: "MS Sans Serif";} </style><a href=\"http://www.MyWebSite.com\">Visit my Web site</a>" );
For sample script, see CtrlGetUrlForLinkClicked Example.
Handling Click Events for Links in HTML Controls
If you use the CtrlSetText function to set HTML control content at run time and the control creation succeeds, CtrlSetText returns 0. If it fails, CtrlSetText returns ISERR_GEN_FAILURE.
To handle click events for links in HTML controls, the WaitOnDialog function returns the control ID of the HTML control (which is also the control ID of the original static text control). A custom dialog script function can contain a case statement that handles the HTML control ID, and then calls the CtrlGetUrlForLinkClicked function to obtain the URL for the link that was clicked. With this link, the script can take any action (such as launching an Internet browser to navigate to the link).
The following behavior occurs when an end user clicks a link for an HTML control that uses the anchor tag:
| • | If the anchor tag does not include the target attribute, or if the target value does not result in a new window, the control ID is returned to the dialog script. This allows for the script to handle link clicks itself. |
| • | If the anchor tag does include the target attribute and its value is _blank or some other equivalent value that results in a new window, no message is sent to the script, and the URL is automatically launched. |
Special Considerations for HTML Controls
If you are adding HTML controls to dialogs, note the following details.
Run-Time Requirements for HTML Controls
The HTML control requires Internet Explorer 5.5 or later for full functionality. If an earlier version is present on a target system, the only way to set the content for the HTML control is to provide an HTML file to CtrlSetText. Note that Internet Explorer does not need to be the default browser on the target system.
HTML Control Support for HTML Files
If you using an HTML file with an HTML control, you must specify the full path to the file through the CtrlSetText function. Otherwise, the InstallScript engine will not know where the file is located. Following is sample InstallScript:
CtrlSetText(szDlg, HTML_CTRL_ID, "[html]file://" + SUPPORTDIR^"aboutpage.htm");
Using an HTML Control for an Email Address
If you want to add a hyperlink that points to an email address, you can use code such as the following:
CtrlSetText(szDlg, HTML_CTRL_ID, "[html]<a href=\"mailto:support@mycompany.com?Subject=Example%20Line\">Send email to Support</a>");
When an end user clicks such a link, a new email message is automatically opened in the target system’s email application. Note that with the mailto link, no message is sent to the script.
HTML Text Content Is Not Formatted
Any content set in an HTML control is passed as is. No formatting of the content is performed. If you need to format any of the content, you can manipulate the content string in script and then pass the content string to CtrlSetText.
Character Count Limits for the Text Property of Static Text Controls
The Text property of static text controls has a maximum limit of 256 characters. Therefore, if you convert a static text control to an HTML control by adding [html] to the beginning of the text content for a control, the maximum number of characters that you can enter is 256; this includes the hyperlinked text as well as all characters for any HTML markup that you specify. If you need to enter more than 256 characters for the content, use the CtrlSetText function to create the control.
See Also
InstallShield 2016 Help LibraryAugust 2016 |
Copyright Information | Flexera Software |