Fixed artifacts in text boxes and other typable things when XPUI_BGIMAGE is enabled
<html>
<head>
<title>ExperienceUI Documentation Content Frame</title>
<link rel=stylesheet href=style.css type=text/css>
<script type=text/javascript src=cmd.js></script>
</head>
<body bgcolor="#FFFFFF" style="background-color:#FFFFFF;margin:0px;padding:0px">
<table border=0 width=100% height=100%>
<tr>
<td valign=top style=margin:10px;padding:10px>
<a name=basic id=basic></a>
<h1>How skins work</h1>
<p style="margin-left: 0.2in">
In the ExperienceUI world, there are two ways of doing the actual skinning. The first - and most common - is the conventional
NSIS-based method of skinning. The second is skinning using an external plugin, such as <a href=wansis.htm>WAnsis</a>. The
define XPUI_SKIN applies only to conventional skins; XPUI_WANSIS_SKIN applies to installers using WAnsis.
</p>
<p style="margin-left: 0.2in">
Blah
</p>
<h1>Basic Settings</h1>
<font face=Verdana style=font-size:8pt>
<script type="text/javascript">
define("XPUI_SKIN", "skinfilename_nodir_noext", "Sets the skin used for your installer. The skins included with the ExperienceUI are Windows XP, Orange, and Modern-blue. Behind the scenes, the ExperienceUI includes a skin file with:<br><code>!include ${NSISDIR}\\Contrib\\ExperienceUI\\Skins\\${XPUI_SKIN}.xpuiskin</code><br><br><b>Note:</b> to use one of the new WAnsis skins (Bliss, LCD, or Forum) please see the <a href=wansis.htm>WAnsis Page</a>.<br>", "undefined<br>Example: <code>!define XPUI_SKIN \"Windows XP\"</code>");
define("XPUI_BRANDINGTEXT", "\"Text\"", "Sets the text at the bottom of the installer.","\" \" [blank string]");
document.write("<div style='margin-left:0.2in'>");
define("XPUI_BRANDINGTEXT_COLOR_FG", "hex_color", "The foreground color of the branding text.", "606060");
define("XPUI_BRANDINGTEXT_COLOR_BG", "hex_color", "The drop shadow color of the branding text.", "808080");
document.write("<\/div>");
define("XPUI_UI", "Path_to_uifile", "Sets the NSIS dialog file used for all of the installer dialogs except IDD_INST (not IDD_INSTFILES). To create custom UI files, use Resource Hacker or another resource editor.", "<code>${NSISDIR}\\Contrib\\ExperienceUI\\UIs\\UI.exe</code>");
define("XPUI_UI_IDDINST", "Path_to_uifile", "The UI file used for dialog 105 (the wrapper dialog for all of the other \"child\" windows.) It is recommended that you leave this at the default setting.", "<code>${NSISDIR}\\Contrib\\ExperienceUI\\UIs\\HeaderUI.exe</code>");
define("XPUI_DISABLEBG", "<i>No parameters</i> (true/false value)", "Define this to disable all of the background effects. Use this if you want to save a little space if you are distributing your program over the web. This define also disables any custom backgrounds that skins may have.", "true/<b>false</b>");
define("XPUI_LEFTLOGO", "Image_file", "The Left Logo is the image on the left of the installer, usually an XP-style \"computer\" graphic. Recommended size: <b>240</b>x<b>349</b> pixels.", "<code>${NSISDIR}\\Contrib\\ExperienceUI\\Skins\\Default\\LeftBranding.bmp</code>");
</script>
<a name=reserve id=reserve></a>
<script type="text/javascript">
define("XPUI_RESERVEFILES", "<i>No parameters</i> (true/false value)", "Define this before inserting language files to have all ExperienceUI files added to the beginning of the installer's data block. This can make the installer loading process a bit faster in large installers.", "true/<b>false</b>");
</script>
<a name=abort id=abort></a>
<h1>Abort Warning</h1>
<p style=margin-left:0.2in>
<font face=Verdana style=font-size:8pt>
An abort warning is a message that shows when you click Cancel. If you don't use an abort warning, the installer will close
as soon as you click Cancel.
</font>
<script type="text/javascript">
define("XPUI_ABORTWARNING", "No parameters (true/false value)", "Define this to make the installer show a confirmation screen when the user clicks Cancel.", "true/<b>false<\/b>");
define("XPUI_ABORTWARNING_TEXT", "String", "The text used on the confirmation message box.", "<div style=margin-left:0.6in;>You are about to quit <NAME> Setup.$\\n<br>$\\n<br>If you quit now, <NAME> will not be installed.$\\n<br>$\\n<br>Do you want to continue?</div>");
</script>
<div style="border: 1px solid #709080; background-color: #C0F0D0; padding: 10px; margin-left: 0.2in">
<b>If you don't use an Abort Warning</b><br>
<br>
If you have an Abort Page in your installer, you may want to use an automatic abort warning in order to make the Abort page
trigger properly. If you aren't using the ExperienceUI's built-in abort warning system, you can insert the following
function to properly invoke the Abort page.<br>
<br>
<script type="text/javascript">
var noset;
function expandFunction(name) {
if(document.getElementById(name+"Function").style.display=="block") {
document.getElementById(name+"Function").style.display="none";
document.getElementById(name+"Toggle").src="../Images/plus.gif";
if(!noset) {
document.getElementById(name+"Trigger").innerText=unescape("Expand "+name+" function");
}
} else {
document.getElementById(name+"Function").style.display="block";
document.getElementById(name+"Toggle").src="../Images/minus.gif";
if(!noset) {
document.getElementById(name+"Trigger").innerText=unescape("Collapse "+name+" function");
}
}
noset=false;
}
</script>
<a href="javascript:expandFunction('abort');"><img id=abortToggle border="0" hspace=3 src="../Images/plus.gif"></a><a href="javascript:expandFunction('abort');" id=abortTrigger>Expand Abort function</a><br>
<div style="margin-left:0.2in;display:none" id=abortFunction><br>
<font face="Courier New" style="font-size: 8pt">
<font color=#0000FF><b>Function </b></font><font color=#000000>.onUserAbort</font><br>
<font color=#0000FF><b>StrCmp</b> </font><font color=#800000><i>$NOABORTWARNING</i></font> <font color=#008080>1</font> <font color=#000000>CloseMe</font><br>
<font color=#0000FF><b>MessageBox </b><font color=#FF8040>MB_YESNO</font><font color=#000000>|</font><font color=#FF8040>MB_ICONQUESTION</font> <font color=#008080>"Are you sure you want to cancel Setup?"</font> <font color=#FF8040>IDNO</font> <font color=#000000>NoAbort</font><br>
<font color=#000080><b># any custom code you want before the Abort page is called here...</b></font><br>
<font color=#008000>!insertmacro </font><font color=#000000>XPUI_USERABORT</font><br>
<font color=#000000>NoAbort:<br>
<font color=#0000FF><b>Abort</b></font><br>
<font color=#000000>CloseMe:</font><br>
<font color=#000080><b># any custom code you want before the installer exits here...</b></font><br>
<font color=#0000FF><b>FunctionEnd</b></font>
</font>
</font>
</font>
</div>
</div>
<br />
<div style="border: 1px solid #709080; background-color: #C0F0D0; padding: 10px; margin-left: 0.2in">
<b>$NOABORTWARNING: The mystery revealed</b><br />
<br />
I just realized that though this "mystery" variable has been used with the ExperienceUI forever past, it never got a
mention in the documentation. Here's why it's here:<br />
<br />
<b>Note:</b> In ExperienceUI versions <=1.1, the variable was $NOABORTWARNING. It was renamed to $NOABORTWARNING in versions 1.11.<br />
<br />
The Abort and InstSuccess pages, as you may have noticed, take advantage of an NSIS hack to make the Cancel button close
the installer window without a prompt. The $XPUI_NOABORTWARNING variable is always declared, even if it isn't used, because
of the way the ExperienceUI references variables. When the Abort page or the InstSuccess page is triggered, it uses
<code>StrCpy $NOABORTWARNING 1</code> to make the .onUserAbort function quit the installer immediately after the Cancel
button (which has become the close button) is clicked.<br />
<br />
The thing is, when I created the first tests of the ExperienceUI code, I was also working on a few installers for some
people. The installers used the Modern UI, but with many custom pages (such as the Install Success page) that later
found their way into the ExperienceUI. I used the $NOABORTWARNING variable to keep track of whether the Cancel button
<i>cancelled</i> the installer or <i>closed the installer window</i>. The variable was renamed to $XPUI_NOABORTWARNING in ExperienceUI version 1.11.<br />
<br />
You can use this variable too - all the ExperienceUI pages and functions understand it. If you know basic window
manipulation (very C++), you can do this quite easily: Disable the "Next" button, and set $XPUI_NOABORTWARNING to 1. When you
click Cancel on the affected page, the installer will quit instantly. Optionally, you can set the text on the Cancel
button to Close or whatever.
</div>
</p>
<a name=colors id=colors></a>
<h1>Dialog Colors</h1>
<p style=margin-left:0.2in>
<script type="text/javascript">
define("XPUI_TEXT_COLOR", "HEX_COLOR", "The color used for all of the text in the installer.", "0xB4D3EA");
define("XPUI_TEXT_BGCOLOR", "HEX_COLOR", "The color used for the background of the installer.", "0x566978");
define("XPUI_TEXT_LIGHTCOLOR", "HEX_COLOR", "The color used on accented text.", "0xFFFFFF");
</script>
</p>
<a name=buttons id=buttons></a>
<h1>Navigation Buttons</h1>
<script type="text/javascript">
define("XPUI_BUTTONTEXT_NEXT", "Text", "The text used on the Next button.", "Next");
define("XPUI_BUTTONTEXT_BACK", "Text", "The text used on the Back button.", "Back");
define("XPUI_BUTTONTEXT_CANCEL", "Text", "The text used on the Cancel button.", "Cancel");
define("XPUI_BUTTONTEXT_CLOSE", "Text", "The text used on the Finish button. Usually \"Done,\" \"Finish,\" or \"Close.\"", "Close");
</script>
<p style=margin-left:0.2in>
After defining custom text for buttons, that text will be used in the next language inserted. Defining any custom button
text after inserting the last language will have no effect in the final installer.
</p>
<a name=pagebg id=pagebg></a>
<h1>Page Background Image</h1>
<p style="margin-left: 0.2in">
You can show a bitmap in the background of your installer's pages. Support for thie feature is still experimental, but it should work
for most pages. Note that Stardock WindowBlinds 5.0 can cause problems with this, and 4.x versions are known to cause radio buttons and
check boxes to not work at all. Also, avoid using icon controls that show an icon with a 32x32 image that contains an alpha channel, as this causes the background
of the icon controls to show up as black.
</p>
<script type="text/javascript">
define("XPUI_BGIMAGE", "No parameters (true/false value)", "Define this to enable the use of a bitmap in the background of the main page area. Support for this feature is experimantal but works for most installers.", "true/<b>false</b>");
define("XPUI_BGIMAGE_BMP", "C:\\Path\\To\\Bitmap.bmp", "The bitmap file used for the background image. I recommend that you start with a blank canvas filled with the value used for XPUI_PAGE_BGCOLOR.", "<NSIS>\\Contrib\\ExperienceUI\\Skins\\Default\\Page.bmp<br />Recommended size: <b>693</b>x<b>512</b>");
</script>
<p style="margin-left: 0.2in">
<b>A note on skins:</b><br />
<br />
When you use a page background image, you may need to change the Left Logo image. If you want to allow the user of your skin to turn the
page background image on or off, you may want to use the following code to be sure that the Left Logo is changed properly.<br />
<br />
<a href="javascript:var noset=true;expandFunction('BGFunction');"><img id=BGFunctionToggle border="0" hspace=3 src="../Images/plus.gif"></a><a href="javascript:var noset=true;expandFunction('BGFunction');" id=BGFunctionTrigger>Expand code</a><br>
</p>
<div style="margin-left:0.3in;display:none" id=BGFunctionFunction><br>
<pre>
<code><span style="font: 10pt Courier New;"><span class="nsis1-directive">!ifdef</span><span class="nsis1-space"> XPUI_PAGE_BGIMAGE
</span><span class="nsis1-directive">!insertmacro</span><span class="nsis1-space"> XPUI_DEFAULT XPUI_LEFTLOGO </span><span class="nsis1-string">"</span><span class="nsis1-variable">${NSISDIR}</span><span class="nsis1-string">\Contrib\ExperienceUI\Skins\MySkin\LeftLogo_PageBG.bmp"
</span><span class="nsis1-directive">!else
</span><span class="nsis1-space"> </span><span class="nsis1-directive">!insertmacro</span><span class="nsis1-space"> XPUI_DEFAULT XPUI_LEFTLOGO </span><span class="nsis1-string">"</span><span class="nsis1-variable">${NSISDIR}</span><span class="nsis1-string">\Contrib\ExperienceUI\Skins\MySkin\LeftLogo.bmp"
</span><span class="nsis1-directive">!endif
</span></span>
</code></pre>
</div>
<a name=header id=header></a>
<h1>Header Image</h1>
<script type="text/javascript">
define("XPUI_HEADERIMAGE_BMP", "Bitmap_file", "The bitmap used for the header background at the top of the installer.", "<code>${NSISDIR}\\Contrib\\ExperienceUI\\Header.bmp</code><br>Recommended size: <b>693</b>x<b>57</b> pixels");
define("XPUI_HEADERIMAGE_NORESIZETOFIT", "No Parameters (true/false value)", "Don't resize the header image to fit the bitmap control. Avoid using this option if your bitmap fits exactly.", "true/<b>false</b>");
define("XPUI_UNHEADERIMAGE_BMP", "Bitmap_file", "The bitmap used for the header background at the top of the <b>uninstaller</b>.", "<code>${NSISDIR}\\Contrib\\ExperienceUI\\Header.bmp</code><br>Recommended size: <b>693</b>x<b>57</b> pixels");
</script>
<a name=bottom id=bottom></a>
<h1>Bottom Image</h1>
<script type="text/javascript">
define("XPUI_NOBOTTOMIMAGE", "No parameters (true/false value)", "By default, the ExperienceUI uses a bitmap at the bottom of the installer window behind the Back, Next, and Cancel buttons. Define this to turn this off and save ~2kb.", "true/<b>false</b>");
define("XPUI_BOTTOMIMAGE_BMP", "Bitmap_file", "The bitmap used for the button background at the bottom of the installer.", "<code>${NSISDIR}\\Contrib\\ExperienceUI\\Bottom.bmp</code><br>Recommended size: <b>693</b>x<b>70</b> pixels");
define("XPUI_UI_BOTTOMIMAGE", "Path_to_uifile.exe", "The IDD_INST dialog file for installers that use bottom images.", "<code>${NSISDIR}\\Contrib\\ExperienceUI\\HeaderUI_BtmImg.exe</code>");
define("XPUI_BOTTOMIMAGE_NORESIZETOFIT", "No Parameters (true/false value)", "Don't resize the bottom image to fit the bitmap control. Avoid using this option if your bitmap fits exactly.", "true/<b>false</b>");
define("XPUI_NO<u>UN</u>BOTTOMIMAGE", "No parameters (true/false value)", "By default, the ExperienceUI uses a bitmap at the bottom of the <b>un</b>installer window behind the Back, Next, and Cancel buttons. Define this to turn this off and save ~2kb.", "true/<b>false</b>");
define("XPUI_UNBOTTOMIMAGE_BMP", "Bitmap_file", "The bitmap used for the button background at the bottom of the <b>uninstaller</b>.", "<code>${NSISDIR}\\Contrib\\ExperienceUI\\Bottom.bmp</code><br>Recommended size: <b>693</b>x<b>70</b> pixels");
</script>
<a name=gradient id=gradient></a>
<h1>Background Gradient</h1>
<script type="text/javascript">
define("XPUI_BGGRADIENT", "No parameters (true/false value)", "Use an NSIS-Standard background gradient for the installer.", "true/<b>false</b>");
define("XPUI_BGGRADIENT_CUSTOMCOLORS", "No parameters (true/false value)", "Use customized colors for the background gradient. Usually, the ExperienceUI sets the text color as the top part, the background color as the bottom gradient, and the light text color as the background text.", "");
define("XPUI_BGGRADIENT_CUSTOMCOLORS_TOP", "HEX_COLOR", "Your own color for the top of the background gradient.", "<XPUI text color>");
define("XPUI_BGGRADIENT_CUSTOMCOLORS_BOTTOM", "HEX_COLOR", "Your own color for the bottom of the background gradient.", "<XPUI text BG color>");
define("XPUI_BGGRADIENT_CUSTOMCOLORS_TEXT", "HEX_COLOR", "Your own color for the text that is usually the product name at the top of the background gradient.", "<XPUI light text color>");
</script>
</td>
</tr>
<tr>
<td valign=bottom style=margin:0px;padding:0px>
<p class=footer>Copyright © 2004-2006 Dan Fuhry. All rights except those explicitly given in the <a href=license_agreement.htm style=color:#A0A0D0 onmouseover="this.style.color='#A0A0A0'" onmouseout="this.style.color='#A0A0D0'">license agreement</a> reserved.</p>
</td>
</tr>
</table>
</body>
</html>