VB.NET For Everyone!

.NET : Install your app and the .NET framework using INNO Setup

Matthew Kleinwaks — Mon, 23 Jun 2008 19:53:00 GMT

Today we are going to look at an alternative to using ClickOnce or Windows Installer MSI to install an application written in .NET.

This article is written for installing an application written in Microsoft .NET 2.0 (does not have to be VB specifically) and including the .NET Framework as part of your installation. The concepts here can be applied to do the same for a .NET 1.1 or .NET 3.x installation, however some specific values will change, and some logic will change (like the fact that .NET 3.x will not run on any Windows below XP SP2, and .NET 2.0 does).

Some History
One of the biggest problems with using an MSI based installer, or ClickOnce to deploy your .NET application, is the need to have multiple installation files. At the least, you generally need 2, a setup.exe bootstrapper to kick things off, and the MSI file which contains the actual files to install. This can be fine when dealing with a CD based installation, but how about internet downloads? Some make use of self extracting zip type files to extract the setup files and launch the bootstrapper, others simply zip the files up and expect you to unzip them and run the setup.exe. There are also 3rd party apps like InstallShield and Wise, however I was looking for a "free" approach to his.

Depending on your target audience, you may want to have a nice, easy to use, single setup.exe that people can download and run without any extra hoops to jump through.

INNO Setup is a free open source installer program written and maintained by Jordan Russell. It has the ability to package everything into a single setup.exe for easy deployment.

Here are some links of importance:

JR Software Homepage
INNO Version used in this article
Newest INNO Version Page
.NET 2.0 Redist File Download
.NET 2.0 (sp1) Redist File Download (Note: This is a full version of .NET Framework, you don't need the above link if you use this one.)

Make sure you always download and install the QuickStart pack installation of Inno versus just the standard one, as it includes a preprocessor
(similar to conditional compiler statements in VB with the # sign). More on this later.

One thing to keep in mind as you start to use INNO Setup, is that it is NOT a .NET installer. It is a generic installer for installing anything from a full blown app, to possibly just a directory of pictures. It is very flexible, albeit with a slight learning curve if you are used to VB programming. I use VB for 95% of my programming, and I found INNO's Pascal Scripting to be pretty easy to pickup, and not required in all cases of use.

Inno setup files have .iss (Inno Setup Script) extensions, and they are nothing more than plain text files. You can write them in notepad if you wish, however using the INNO program gives you syntax highlighting (plus it is free, and we need it to compile the script when we are done).

This article does not require you have existing knowledge of INNO Setup, however if you do, you will likely understand much of this article a bit better than those who do not. For those of you who are new to INNO Setup, this is not going to teach you everything you will want to know about it, so I suggest you visit the INNO website and look over some of the docs, tutorials, and newsgroups there. That being said, you can take this script and mostly change around values of the fields to fit your own application and have a working installer.

This article is also not a tutorial on how to use INNO Setup. It is an article on how to use INNO Setup to install the .NET Framework. Yes there is a difference, and that difference is I am not going to go into great detail about what each property and method of the setup does. That would take a book, not a blog posting.

Time to get down to business

Ok, so now that we have gotten those facts out of the way, and you have downloaded and installed either the specific version I used for this example (5.1.9), or the newest version.
(Important note as of this article, the newest version of INNO 5.2.3 works fine with this script)

So we are going to go through the entire setup file, section by section, and talk about what is going on.

So open up INNO setup, and select "Create a new empty script file", or just click cancel on the welcome dialog. You will be at the script editor window, which looks similar to a standard text editor like notepad.

Lets add some comments to the top of the script:

;Example .NET Setup Script
;written in Inno Setup 5.1.9 (ISPP 5.1.8.0)
;2008 Matthew Kleinwaks
;www.ZerosAndTheOne.com
;change these comments as needed for your own app

Now we will define some preprocessor variables

#define SourceFileDir "c:\work\myapp"
#define IncludeFramework true
#define IsExternal ""

Basically, these preprocessor variables are generated BEFORE the script is compiled. This is useful to do things like set options. Perhaps you want to have a demo version as well as the full version of your product. You could use a preprocessor directive to indicate if its the demo or not, which can allow for boolean logic (if statements) to include one file or another based on if its a demo or not. That is just one example, but you get the idea.

SourceFileDir is a directory on my machine where the release version files of my actual application are. This would be the exe, dll files, any support files that are part of the application itself, like pictures, data files, eula, readme, etc.
IncludeFramework is simply a boolean to indicate if you want the framework packaged and installed. Sometimes it can be convenient to NOT include it.
IsExternal is also a directive that we will use to determine if in fact we want to package the app files with the setup.exe, or keep them separate. Obviously for a download we want them all to be part of one setup.exe file, however sometimes for distribution on CD, it is better to package the files loosely instead of all packed into one file. If you do want the files external, you should replace the "" in this line with "external" (including the quotes). More on why it works like that further down in the [files] section.

So now lets write out the sections of the setup file. After that, we will create the code section to do all of our custom .NET installer coding.

The first section is [Setup]. It defines many of the properties that make up the installer's look, feel, and many textual attributes.

[setup]
;name of your application
AppName=MyApp
;repeat name of application. (otherwise you get
;multiple entries in add/remove programs)
AppVerName=MyApp
;app publisher name
AppPublisher=zerosandtheone.com
;app publisher website URL
AppPublisherURL=http://www.zerosandtheone.com
;app publisher support URL
AppSupportURL=http://www.zerosandtheone.com/support
;app publisher updates URL
AppUpdatesURL=http://www.zerosandtheone.com
;default directory {pf} is a constant for
;program files. See INNO help for all constants
DefaultDirName={pf}\zerosandtheone\MyApp
;default group name in the programs
; section of the start menu
DefaultGroupName=MyApp
;Boolean to disable allowing user to customize
;start menu entry during installation
DisableProgramGroupPage=yes
;Boolean to warn if directory user picks
;already exists
DirExistsWarning=no
;directory where uninstaller exe will be
;this will be where our app is
;the constant we use is {app}
UninstallFilesDir={app}
;Location of the license file
LicenseFile={#SourceFileDir}\eula.rtf
;file to show before install (I show sys requirements)
InfoBeforeFile={#SourceFileDir}\sysreq.rtf
;file to show after install (I show readme)
InfoAfterFile={#SourceFileDir} eadme.txt
;Custom image to show on left side of installer
WizardImageFile={#SourceFileDir}installlogo.bmp
;Icon for uninstall in add/remove programs
;I use whatever my apps icon is
UninstallDisplayIcon={app}\MyApp.exe
;Version number of your installer (not your app)
VersionInfoVersion=1.0.0.0
;If IncludeFramework, append _FW to end of compiled setup;
I do this to make it easy to compile a version with and
;without the framework included
#if IncludeFramework
OutputBaseFilename=setup_FW
#else
OutputBaseFilename=Setup
#endif
;Directory where setup.exe will be compiled to
OutputDir={#SourceFileDir}\setup

So there you have it. The comments should explain what is going on for you. Some of these fields are optional and can be removed if not needed. Likewise there are some others that I do not use. See the INNO help file for a full list of what is available to the [setup] section.

The next section is the [files] section. This section defines what files should be compiled into the setup.exe file. Our example will simply consist of an exe, a readme.txt and the .NET framework redistributable file.

[files]
Source: {#SourceFileDir}\MyApp.exe; DestDir: {app}; Flags: ignoreversion {#IsExternal}
source: {#SourceFileDir}readme.txt; DestDir: {app}; Flags: ignoreversion {#IsExternal}
#if IncludeFramework
Source: {#SourceFileDir}\dotnetfx.exe; DestDir: {tmp}; Flags: ignoreversion {#IsExternal} ; Check: NeedsFramework
#endif

So what we have here are 3 lines indicating our source files, where they will go on the target machine, and any flags we need to associate. Again see INNO help for all possible flags and properties here. (I will mention to refer to INNO Help a lot because it is too robust to cover every aspect in one article, however you will end up with a fully working script by the end of this one). Notice that while we install myapp.exe and readme.txt to the {app} directory, we unpack the dotnetfx.exe (framework redist file) to a temp directory. The constant {app} actually translates at install time to whatever directory the user selects for installation. While we always like to assume they will install to c:\program files\ that will never be the case 100% of the time. IgnoreVersion just means we are going to copy the file no matter what, you can put restrictions here to only copy the file if its a newer version, etc. Also notice our {#IsExternal} directive here. I mentioned earlier that its value should be either "" or "external". That is because these preprocessor directives are compiled into literal strings for use when the setup is compiled. What that means is, when the value of #IsExternal is "" the line looks like this once compiled:

Source: {#SourceFileDir}\MyApp.exe; DestDir: {app}; Flags: ignoreversion

however if the value is "external" then the line compiles like this:

Source: {#SourceFileDir}\MyApp.exe; DestDir: {app}; Flags: ignoreversion external

Which adds the external flag to this file. The external flag tells the setup that the file to install is actually not packed into the installer, but a loose file included along with it. This makes preprocessor directives very powerful to customize your installer when used in this way. The Check: NeedsFramework line for the .NET redist file will call up a custom function to check and see if the machine even needs the .NET framework or not. We will define that function when we get to the code section of the script.

Now lets specify the shortcuts we want made.

[icons]
Name: {group}\MyApp; Filename: {app}\MyApp.exe; WorkingDir: {app}
Name: {group}\Remove MyApp; Filename: {uninstallexe}; WorkingDir: {app}
Name: {userdesktop}\MyApp; Filename: {app}\MyApp.exe; WorkingDir: {app}

So we are putting a shortcut in the programs section of the start menu, as well as the desktop. We also put an uninstall shortcut in the start menu folder. Everything that is in curly braces { } is a constant that INNO translates at install time into a real string value. Where can you find all these constants? Yup, you guessed it, in the INNO Help file.

On to the [Run] section. This section defines what processed should be run as part of the installation.

[Run]

#if IncludeFramework
Filename: {tmp}\dotnetfx.exe; Parameters: "/q:a /c:""install /l /q"""; WorkingDir: {tmp}; Flags: skipifdoesntexist; StatusMsg: "Installing .NET Framework if needed"
#endif

Filename: {win}\Microsoft.NET\Framework\v2.0.50727\CasPol.exe; Parameters: "-q -machine -remgroup ""MyApp"""; WorkingDir: {tmp}; Flags: skipifdoesntexist runhidden; StatusMsg: "Setting Program Access Permissions..."

Filename: {win}\Microsoft.NET\Framework\v2.0.50727\CasPol.exe; Parameters: "-q -machine -addgroup 1.2 -url ""file://{app}/*"" FullTrust -name ""MyApp"""; WorkingDir: {tmp}; Flags: skipifdoesntexist runhidden; StatusMsg: "Setting Program Access Permissions..."

Lets go over each of these 3 lines here. The first one installs the .NET framework. The Parameters we pass along with this file are simply those to make the installation silent (show no UI while installing). You may or may not want this, it is up to you. For full details on the exact meaning of the command line switch used for the framework installation, visit this MSDN Page on the subject. The StatusMsg field lets you specify a message that INNO displays while this process is running. I left it off for space saving here, but I often also put "this will take several minutes..." because lets face it, installing the .NET framework on an average computer does take a few minutes. The skipifdcoesntexist flag is important because remember that we only extracted the framework to the temp directory if the system didn't have the framework installed, so if it doesn't exist, then chances are the user already had the framework (or is out of disk space!).

The other 2 lines simply run caspol.exe to set permissions using a little "url" trick. If you are not familiar with CasPol, it is the Code Access Security Policy utility. .NET code has an extra layer of code security hooked into the runtime, and by default your local drives run with full trust, and your network drives run with partial trust. Long story short, if your customer installs your program to a network mapped drive, there is a good chance they will start getting weird security exceptions because you did not design your app to run at partial trust (or your app simply NEEDS full trust to do whatever it is your app does). So we have INNO set permissions to give full trust to wherever the user installed the app. If its the local drive, they already had the permissions, and if its a network drive, this will give them the permissions to the installation folder. Its a win/win scenario. You may wonder why there are 2 entries though, and that is because we first try to remove an existing entry if it is there, to avoid duplicate entries in caspol. If there was no entry to begin with, the method simply completes without doing anything.

The skipifdoesntexist flag just tells INNO that if the file we are working with doesn't exist for some reason, don't try to launch it. The only time it won't exist is in weird scenarios of framework installation failure, etc.

Like the [run] section, there is also an [uninstallrun] section. This section defines what will run when the program is uninstalled. The only thing I put here, is to remove the caspol entry, just like we did in the run section. It is better to do it here, the entry in the run section is just a backup.

[UninstallRun]

Filename: {win}\Microsoft.NET\Framework\v2.0.50727\CasPol.exe; Parameters: "-q -machine -remgroup ""MyApp"""; Flags: skipifdoesntexist runhidden;

So up to this point, we have finished our entire INNO script file, with the exception of the code section. INNO implemented a pascal scripting code section at some point in its life to allow you to extend and customize the installation experience. There is little you can not do, but this flexibility comes at the cost of knowing how to write the code. The Inno Setup IDE is not nearly as advanced as the Visual Studio IDE, so writing code can be a bit difficult at times, however I am going to take you through my standard setup code, and explain what it does.

The code section starts with, yes you guessed it, a [code] heading.

First we are going to define some functions that we will use to aid our setup process.

I am not going to go over every single line here in detail. The functions are pretty short, and do specifically only what they say. Most of them are just checking the state of the system for a given value, like if the framework exists, if a service pack is installed, etc. Most of them query a registry key, check a file version, or something similar to see what is already on the system.

[code]

// Indicates whether .NET Framework 2.0 is installed.
function IsDotNET20Detected(): boolean;
var
    success: boolean;
    install: cardinal;
begin
    success := RegQueryDWordValue(HKLM, 'SOFTWARE\Microsoft\NET Framework Setup\NDP\v2.0.50727', 'Install', install);
    Result := success and (install = 1);
end;

//RETURNS OPPOSITE OF IsDotNet20Detected FUNCTION
//Remember this method from the Files section above
function NeedsFramework(): Boolean;
begin
Result := (IsDotNET20Detected = false);
end;

//CHECKS TO SEE IF CLIENT MACHINE IS WINDOWS 95
function IsWin95 : boolean;
begin
Result := (InstallOnThisVersion('4.0,0', '4.1.1998,0') = irInstall);
end;

//CHECKS TO SEE IF CLIENT MACHINE IS WINDOWS NT4
function IsWinNT : boolean;
begin
Result := (InstallOnThisVersion('0,4.0.1381', '0,4.0.1381') = irInstall);
end;

//GETS VERSION OF IE INSTALLED ON CLIENT MACHINE
function GetIEVersion : String;
var
IE_VER: String;
begin
{First check if Internet Explorer is installed}
if RegQueryStringValue(HKLM,'SOFTWARE\Microsoft\Internet Explorer','Version',IE_VER) then
      Result := IE_VER
else
    {No Internet Explorer at all}
    result := '';
end;

//GETS THE VERSION OF WINDOWS INSTALLER DLL
function GetMSIVersion(): String;
begin
GetVersionNumbersString(GetSystemDir+'\msi.dll', Result);
end;

//LAUNCH DEFAULT BROWSER TO WINDOWS UPDATE WEBSITE
procedure GoToWindowsUpdate;
var
ErrorCode: Integer;
begin
if (MsgBox('Would you like to go to the Windows Update site now?' + chr(13) + chr(13) + '(Requires Internet Connection)'
, mbConfirmation, MB_YESNO) = IDYES) then
ShellExec('open', 'http://windowsupdate.microsoft.com','', '', SW_SHOW, ewNoWait, ErrorCode);
end;

Those are all of our helper functions. Now lets define a few functions that are built into INNO setup. When I say built in, I mean these are functions that INNO already knows the name of, and will run at a certain point if you define them.

There are many, but the ones we are going to use are

InitializeSetup()
GetCustomSetupExitCode()

InitializeSetup() is the first thing that runs when the installer starts up, so we will add in our custom logic to this routine to make the installer do the checks we want to perform.

GetCustomSetupExitCode() is something that runs when setup is complete. We use this method to check for the .NET Framework (because at this point it should be installed) and give an error message if we don't find it. There are any number of reasons why the installation could fail, so all we really do here is check and alert the user if it did fail.

I will define GetCustomSetupExitCode() first because it is shorter and self explanatory.

//IF SETUP FINISHES WITH EXIT CODE OF 0, MEANING ALL WENT WELL
//THEN CHECK FOR THE PRESENCE OF THE REGISTRY FLAG TO INDICATE THE
//.NET FRAMEWORK WAS INSTALLED CORRECTLY
//IT CAN FAIL WHEN CUST DOESN'T HAVE CORRECT WINDOWS INSTALLER VERSION
function GetCustomSetupExitCode(): Integer;
begin
if (IsDotNET20Detected = false) then
    begin
      MsgBox('.NET Framework was NOT installed successfully!',mbError, MB_OK);
      result := -1
    end
end;

Now on to the InitializeSetup. This routine is pretty long, because it contains all the checks we want to do before allowing the user to install. Returning False from this routine aborts the setup.

We perform the following checks

If Windows 2000, require at least SP3
If WIndows XP, require at least SP2
If Windows 95 or NT, don't install at all
If NT based (2000, XP, 2003, Vista), require MSI Installer 3 or higher
If 9x based (98, ME), require MSI Installer 2 or higher
If IE version is less than version 5.01, don't install
If admin is not logged on, don't install (.NET Framework install requires admin rights)

So lets get to the code shall we:

function InitializeSetup: Boolean;
var
Version: TWindowsVersion;
IE_VER: String;
MSI_VER: String;
NL: Char;
NL2: String;
begin

NL := Chr(13);
NL2 := NL + NL;

// Get Version of Windows from API Call
GetWindowsVersionEx(Version);

// On Windows 2000, check for SP3

if Version.NTPlatform and
     (Version.Major = 5) and
     (Version.Minor = 0) and
     (Version.ServicePackMajor < 3) then
begin
    SuppressibleMsgBox('When running on Windows 2000, Service Pack 3 is required.' + NL +
                       'Visit' + NL2 +
                       ' *** http://windowsupdate.microsoft.com ***' + NL2 +
                       'to get the needed Windows Updates,' + NL +
                       'and then reinstall this program',
                        mbCriticalError, MB_OK, MB_OK);
    GoToWindowsUpdate;
    Result := False;
    Exit;
end;

// On Windows XP, check for SP2
if Version.NTPlatform and
     (Version.Major = 5) and
     (Version.Minor = 1) and
     (Version.ServicePackMajor < 2) then
begin
    SuppressibleMsgBox('When running on Windows XP, Service Pack 2 is required.' + NL +
                       'Visit' + NL2 + ' *** http://windowsupdate.microsoft.com ***' + NL2 +
                       'to get the needed Windows Updates,' + NL +
                       'and then reinstall this program',
                       mbCriticalError, MB_OK, MB_OK);
    GoToWindowsUpdate;
    Result := False;
    Exit;
end;

//IF WINDOWS 95 OR NT DON'T INSTALL
if (IsWin95) or (IsWinNT) then
begin
    SuppressibleMsgBox('This program can not run on Windows 95 or Windows NT.',
      mbCriticalError, MB_OK, MB_OK);
    Result := False;
    Exit;
end;

//CHECK MSI VER, NEEDS TO BE 3.0 ON ALL SUPPORTED SYSTEM EXCEPT 95/ME, WHICH NEEDS 2.0)
MSI_VER := GetMSIVersion
if ((Version.NTPlatform) and (MSI_VER < '3')) or ((Not Version.NTPlatform) and (MSI_VER < '2')) then
    begin
      SuppressibleMsgBox('You do not have all the required Windows Updates to install this program.' + NL +
                         'Visit *** http://windowsupdate.microsoft.com *** to get the needed Windows Updates,' + NL +
                         'and then reinstall this program',
                         mbCriticalError, MB_OK, MB_OK);
      GoToWindowsUpdate;
      Result := False;
      Exit;
end;

//CHECK THE IE VERSION (NEEDS TO BE 5.01+)
IE_VER := GetIEVersion;
if IE_VER < '5.01' then
    begin
      if IE_VER = '' then
        begin
          MsgBox('Microsoft Internet Explorer 5.01 or higher is required to run this program.' + NL2 +
                 'You do not currently have Microsoft Internet Explorer installed, or it is not working correctly.' + NL +
                 'Obtain a newer version at www.microsoft.com and then run setup again.', mbInformation, MB_OK);
        end
      else
        begin
          MsgBox('Microsoft Internet Explorer 5.01 or higher is required to run this program.' + NL2 +
                 'You are using version ' + IE_VER + '.' + NL2 +
                 'Obtain a newer version at www.microsoft.com and then run setup again.', mbInformation, MB_OK);
        end

      GoToWindowsUpdate;
      result := false;
      exit;
end;

//MAKE SURE USER HAS ADMIN RIGHTS BEFORE INSTALLING
if IsAdminLoggedOn then
    begin
      result := true
        exit;
    end
else
    begin
      MsgBox('You must have admin rights to perform this installation.' + NL +
             'Please log on with an account that has administrative rights,' + NL +
            'and run this installation again.', mbInformation, MB_OK);
        result := false;
    end
end;
end.

So there you have it. The completed code section of the script. You now have a fully functional INNO setup script that will package the .NET 2.0 framework with your program into a single setup.exe, extract it at install time if needed, and install it silently. The script also checks to make sure the user has admin rights, has the needed service pack levels for certain operating systems, has the needed versions of things like MSI installer and Internet Explorer. There may be other checks you want to do (or even some you want to omit) so I hope my script is a good jumping off point for you to get into customizing your own. My code also offers in several failure spots due to system requirements to launch the windows update page so users can get the updates they need. You would be surprised how many people are not even running SP2 on Windows XP even though it has been out a long time now and we are already up to SP3.

Next time, I plan to show you how to associate a file type with your program at install time. For example, maybe your app is a text editor, and you want to associate *.txt files with your program when it is installed. There are a few registry keys involved, and we will go over them in detail. I will also show you how to install a font file, as well as adding some custom functionality to the UI of the installer, to perform even more custom actions. Then I will go into detail about detecting if the user has the .NET Framework installed from an ASP, PHP, or ASP.NET Page and Internet Explorer (Sorry FireFox users, it doesn't work for you). This can be useful when you want to offer your user a download with or without the framework (to save the 20+MB) based on if they need it or not.

You can download the complete script file as it appears in this article from the media download page.

MSDN: Contest for free MSDN Subscription for 1 year.

Matthew Kleinwaks — Fri, 13 Jun 2008 13:53:00 GMT

So Microsoft sent me a little envelope the other day, and inside were 3 cards, each for a 1 year MSDN Visual Studio Team System 2008 Team Suite Premium Subscription.

Wow that is a mouthful huh?

So I already have this same subscription, and these cards were not intended for me to use, they were intended for me to GIVE OUT to the community so developers who are not MVPs can get access to this tremendous library of software and knowledge that can help you along your development journey. Sure, I bet Microsoft is also hoping a few people RENEW these subscriptions after the 1 year is over, but it is still a VERY generous gesture none the less. I don't know if you have looked at the price tag for these subscriptions, but they are not cheap (around $11,000 USD).

So one already went to a friend and fellow developer who is not an MVP, however most of my dealings with the community are online, so I want to extend this offer online.

I will be awarding 1 MSDN subscription to anyone who submits an essay titled "What I will do with an MSDN subscription, and why I should have one"
(and you thought your essay writing days ended when school did!)

I will review all essays and I will pick 1 winner based on what I personally liked the best.

I had thought about a coding contest, however it is too easy for people to pull code off the net and pass it off as their own, unfortunately.

Rules for Essay:

There is no minimum or maximum length. Just keep in mind your 2 sentence essay will likely not do so well against someone else's 1 page essay. Likewise your 20 page "chapter" will probably bore me.
English only
Submission deadline is 7-31-2008 (anything in my mailbox on 8-1 won't be read)
Email your essay to mattzerosandtheone.com (I will respond to everyone to confirm receipt of their essay)
Include your name in the essay
By submitting an essay, you are giving me the right to use them on the site if I wish. The winning essay will most likely be displayed on this site, so keep that in mind. The others will most likely not be.

Check back to this posting or the home page for the latest updates on this contest. I will post the number of submissions I have gotten, as well as my opinion on the submissions so far. Good luck and I look forward to reading your essays.

VB.NET : Extended Combobox to better visually handle being disabled

Matthew Kleinwaks — Mon, 12 May 2008 21:51:00 GMT

If you do any WinForms programming then chances are you have used comboboxes, and perhaps at one point or another, you disabled one of those comboboxes because you did not want the user to be able to make a selection. This works fine, however I actually was getting some complaints from users of some of my software apps saying it was too hard to read the disabled text in a combo. Sometimes just because a feature is disabled, does not mean that the data being displayed in it is of no importance.

So today lets see how we can change this standard functionality to make things a bit easier on our end users.
We will use Visual Basic .NET to extended the standard WinForms .NET combobox control.

Lets start by taking a look at the demo. Here we see 2 disabled comboboxes. The top one is a standard WinForm combobox, which has a gray on gray appearance, and can be pretty hard to read. This demo uses larger fonts, so at a smaller font size, it becomes even more difficult. The second one is the extended ComboBox, and you can see that the ForeColor has stayed black, and the BackColor is gray indicating it is disabled. Much easier to read. So lets see what the code looks like to accomplish this.

Like all the extended controls you can make from the standard WinForm controls, we need to inherit from the control we want to extend, in this case Combobox.

The real trick here is that we are never going to actually make the control disabled. We are simply going to keep track of if it SHOULD be disabled, and stop certain actions from happening in that case. Those actions would be the ability to drop down the combo to make a selection, or to type in the textbox portion of the combo. Take those away, and the combobox is essentially disabled. The other thing we need to take into account, is the default context menu, which gives the user access to features like paste.

In order to do this, we setup a few private fields to keep track of the disabled/enabled state manually.

Here is the start of our class

' 2008 - ZerosAndTheOne.com
' Matthew Kleinwaks
 
'Extended Combobox Control for better 
'handling of disabled appearance
 
Option Strict On
Option Explicit On
 
Imports System.Windows.Forms
 
Public Class ComboboxEx
    Inherits ComboBox
 
 
#Region "Private Backing Fields"
    ''' <summary>
    ''' Private backing field for the shadowed enabled property
    ''' </summary>
    Private _Enabled As Boolean = True
 
    ''' <summary>
    ''' BackColor of control when it is enabled
    ''' </summary>
    Private _enabledBackcolor As Color = MyBase.BackColor
 
    ''' <summary>
    ''' BackColor of a control when it is disabled
    ''' </summary>
    ''' <remarks></remarks>
    Private _disabledBackColor As Color = Color.LightGray
#End Region

Note it is just 3 private fields we will use. One to keep track of the enabled state, and 2 to keep track of the BackColor, depending on the enabled state. The reason we use these 2 BackColor fields, is because we set the controls underlying BackColor property to one of these when the enabled state changes, so we need to keep track of what each color should be when enabled does change.

Next lets define our public fields that will be exposed to the consumer of this control.

#Region "Public Exposed Fields"
 
    ''' <summary>
    ''' Gets or Sets the value indicating if this control is enabled
    ''' </summary>
    ''' <value>Boolean</value>
    ''' <returns>True of control is enabled, otherwise false</returns>
    ''' <remarks>This property shadows the ComboBox base class enabled property</remarks>
    Public Shadows Property Enabled() As Boolean
        Get
            Return _Enabled
        End Get
        Set(ByVal Value As Boolean)
            If _Enabled <> Value Then
                _Enabled = Value
                OnEnabledChanged(New EventArgs)
            End If
        End Set
    End Property
 
    ''' <summary>
    ''' Gets or Sets the BackColor of the control when it is disabled
    ''' </summary>
    ''' <value>Color Structure</value>
    Public Property DisabledBackColor() As Color
        Get
            Return _disabledBackColor
        End Get
        Set(ByVal value As Color)
            _disabledBackColor = value
            If Not _Enabled Then
                MyBase.BackColor = _disabledBackColor
            End If
        End Set
    End Property
 
    ''' <summary>
    ''' Gets or Sets the BackColor of the control when it is enabled
    ''' </summary>
    ''' <value>Color Structure</value>
    ''' <remarks>Shadows the base class BackColor property</remarks>
    Public Shadows Property BackColor() As Color
        Get
            Return _enabledBackcolor
        End Get
        Set(ByVal value As Color)
            If _enabledBackcolor <> value Then
                _enabledBackcolor = value
                MyBase.BackColor = _enabledBackcolor
            End If
        End Set
    End Property
 
#End Region
 

So just like we have 3 backing fields, we have 3 public properties. The biggest thing to note is that 2 of these properties (BackColor and Enabled) are declared shadows. This means they hide and replace the functionality that the base Combobox class provided for these given properties. It is now totally up to us to handle these properties in our new class.

To do the magic here, we will override a few protected methods from the combobox base class, and add our custom functionality.

Lets start with OnEnabledChanged. This is the method that is called when Enabled is changed. In the Enabled public property we defined above, we call this method.

    ''' <summary>
    ''' When the shadowed enabled property changes, this method is called
    ''' </summary>
    Protected Overrides Sub OnEnabledChanged(ByVal e As System.EventArgs)
 
        'COMMON ROUTINE FOR TOGGLING ENABLED STATUS
        ToggleEnabled()
 
        'SEND NOTIFICATION TO BASE CLASS
        MyBase.OnEnabledChanged(e)
 
    End Sub

Pretty simple (we will define the ToggleEnabled method after we define all our overrides).

Next is the PreProcessMessage override. We use this to look at key presses and decide if we want to throw them out, or let them pass to the control to do whatever the given keypress might do. Basically in this example, if the control is enabled, we don't do anything at all, so that is the first thing we check. Next we allow through key presses like Tab, Left, and Right. You could customize what you allow based on the needs of your program.

    'OVERRIDE PreProcessMessage TO LOOK FOR KEY PRESSES AND FILTER THEM
    Public Overrides Function PreProcessMessage(ByRef msg As Message) As Boolean
 
        'PREVENT KEYBOARD ENTRY IF CONTROL IS DISABLED
        If Not _Enabled Then
 
            'CHECK IF ITS A KEYDOWN MESSAGE (&H100)
            If msg.Msg = &H100 Then
 
                'GET THE KEY THAT WAS PRESSED
                Dim key As Int32 = msg.WParam.ToInt32
 
                'ALLOW TAB, LEFT, OR RIGHT KEYS
                If key <> Keys.Tab OrElse _
                   key <> Keys.Left OrElse _
                   key <> Keys.Right Then
 
                    Return True
 
                End If
            End If
        End If
 
        'CALL BASE METHOD SO DELEGATES RECEIVE EVENT
        Return MyBase.PreProcessMessage(msg)
 
    End Function
 

Next we override the WndProc method. In here we are looking for 2 possible messages, which have to deal with the drop down of the list in the combobox. We don't want that to happen when the control is disabled, so we filter out those specific messages, and allow all other messages to go through as normal.

    'OVERRIDE WndProc TO LOOK FOR DROP DOWN MESSAGES AND FILTER THEM
    Protected Overrides Sub WndProc(ByRef m As Message)
 
        'PREVENT DROPDOWN LIST DISPLAYING IF READONLY
        If Not _Enabled Then
            If m.Msg = &H201 OrElse m.Msg = &H203 Then
                Return
            End If
        End If
 
        'CALL BASE METHOD SO DELEGATES RECEIVE EVENT
        MyBase.WndProc(m)
    End Sub
 

Finally, the last override we need to do, is the OnParentEnabledChanged method. This is because if the control is in a container, like a groupbox or panel, and you set the container's enabled property to false, you would expect the combobox to also have it's enabled property set to false. However, the parent control does not simply loop its child controls and set their enabled properties. It actually calls the OnParentEnabledChanged for each child, and lets the child handle what it want's to do in that case. If the control is enabled, we pass through the message like normal. If it is disabled, then we call the ToggleEnabled routine, which is our last routine to define.

    'WHEN THE CONTROL IS IN A CONTAINER, AND THE CONTAINER'S ENABLED PROPERTY
    'IS SET TO FALSE, THIS CONTROL GETS ITS OnParentEnabledChanged CALLED
    'NOT JUST THE CONTROLS ENABLED PROPERTY SET SO WE OVERRIDE THIS, AND 
    'TOGGLE ENABLED STATE ACCORDINGLY
    Protected Overrides Sub OnParentEnabledChanged(ByVal e As System.EventArgs)
 
        _Enabled = MyBase.Parent.Enabled
 
        If _Enabled Then
            MyBase.OnParentEnabledChanged(e)
        Else
            ToggleEnabled()
        End If
    End Sub
 

So it is time to define our ToggleEnabled routine. It is actually pretty simple. We set tabstop to false if the control is disabled, and true if it is enabled, so users won't set focus to it with the tab key. We also set the ContextMenuStrip equal to a New ContextMenuStrip. This actually causes NO menu to appear when the control is right clicked, since the NEW context menu we make has no menu items on it. Setting this property to nothing will bring back the standard cut/copy/paste context menu. Keep this all in mind if you happen to use a custom context menu on this control. We also set the BackColor property to our desired colors were, and also set the SelectionLength to 0. This just deselects any selected text, and is really optional and up to you.

#Region "Support Methods"
    'COMMON ROUTINE FOR TOGGLING ENABLED STATE
    Private Sub ToggleEnabled()
 
        'IF THE CONTROL IS DISABLED, TURN OFF ITS TABSTOP
        MyBase.TabStop = _Enabled
 
        'IF THE CONTROL IS DISABLED, SET ITS CONTEXT MENU TO
        'A DUMMY NEW CONTEXT MENU SO WE DON'T GET THE
        'DEFAULT CONTEXT MENU, OTHERWISE SETTING IT TO
        'NOTHING REAPPLIES THE DEFAULT CONTEXT MENU
        'ALSO SET BACK COLOR ACCORDINGLY
        If Not _Enabled Then
            MyBase.ContextMenuStrip = New ContextMenuStrip
            MyBase.BackColor = _disabledBackColor
        Else
            MyBase.ContextMenuStrip = Nothing
            MyBase.BackColor = _enabledBackcolor
        End If
 
        'DESELECT ANY TEXT FROM COMBOBOX
        Me.SelectionLength = 0
 
    End Sub
#End Region
 

So that all there is to it. We end up with these results:

Attached is the source code for this project in Visual Studio 2008 format, targetting .NET 2.0

As always, please leave your comments and suggestions.