Stub Installer GUI¶
The stub installer’s primary GUI is built using the web platform, rendered by the native Windows browser control
IWebBrowser2, which is based on Internet Explorer (Microsoft never updated it to use Edge 3).
This is all driven by a custom NSIS plugin, called WebBrowser. The plugin’s source code can be found in the directory
Note that not 100% of the stub UI is built using WebBrowser; we also have message boxes which use the Windows TaskDialog function, invoked from NSIS code using the standard System plugin.
Changing the UI¶
The HTML file for each page is always the same regardless of the branding, so it’s kept in the
installer directory next to
Each branding directory (
/browser/branding/*) contains a CSS file for each page, which specifies how the page should be laid out and rendered. These are normal CSS files and can easily be modified to change or redesign one or both pages for any or all brandings. Currently there are two completely different layouts, one for release and another for all other brandings, and the two differ only in this CSS file and in the background image file (also in the branding directory).
The most severe constraint on the web UI is that the browser engine must be configured to run in Internet Explorer 8 mode. This is because the installer must run correctly on an unpatched Windows 7 installation with no service packs or other updates, and that is the version of IE that such an installation provides. That means this constraint can only be relaxed if Firefox’s OS support changes to exclude unpatched Windows 7 (i.e., either dropping Windows 7 entirely or requiring Service Pack 1).
Image assets (meaning only the background image at the moment) can be any format IE8 can open, including JPEG, GIF, or PNG, but any newer formats like WebP won’t work. SVG isn’t supported until IE9.
Fonts should be limited to those that a default Windows 7+ installation provides, which may vary based on locale (it is possible to specify a specific font to use for a certain locale).
The size of the window is difficult to change, and doing so would affect all brandings and require redesigning the background art, so changing that should be avoided.
Care should be taken to make sure that accessibility is maintained, and best practices for web accessibility should be followed. For example, the installing page contains a progress bar. Normally, and in keeping with best practices, this would be implemented using a
<progress> element, but IE8 doesn’t support those, so it has to be built manually out of divs instead. Because this is an inherently inaccessible design, appropriate ARIA attributes are used so that the control is presented to accessibility tools as a real progress bar.
RegisterCustomFunction export, passing it the address (as obtained from the
Init and before
ShowPage. The plugin wraps that address in a native C++ function, and passes it to the WebBrowser control to register with its IDispatch implementation. That code allocates a
There is currently a new control called WebView2 in development which uses the Chrome-based Edge engine, but it’s unfinished as of this writing and would only work on machines with Chrome-based Edge installed anyway.
Previously, the stub installer’s UI was based on nsDialogs, and used its timer implementation, so when nsDialogs was removed an alternative was needed. The replacement timers don’t strictly need to be provided by the WebBrowser plugin, but it was the convenient place to put those functions.