VB.NET For Everyone! : VB.NET

VB.NET Include a font as an embedded resource in your application

Matthew Kleinwaks — Fri, 20 Nov 2009 06:05:00 GMT

Today I am going to show you how you can take a font file, and include it in your VB.NET WinForms application. This means you can load the font at runtime, and use it on your controls without requiring the user to have the font installed on their system. This can come in handy when you want to use a custom font, but your app needs to run without admin rights (because of ClickOnce or other least privileged requirements). Without admin rights you cannot install fonts on a system. (Note: I have seen some workarounds to this, but they require 3rd party utilities).

This is a pretty simple example, and there is not a ton of code. So lets get right down to it:

First lets see the end result.

Here is what the form looks like when I run it normally

Here is what the form looks like when I click the button and load the custom font (which happens to be a digital clock looking font)

The code to do this? Let's take a look. I created a new Windows Forms application, and added a ttf (true type font) file to the resources section of my project. It will be stored under the "files" section of the resources, which means accessing this font in code from the resources will just return a byte array of the file.

I created a module and put all the code needed to load the custom font in there. That way you can make quick calls to it to setup the custom font on your controls.

'MATTHEW KLEINWAKS
'ZerosAndTheOne.com
'2009
'CUSTOM FONT LOADED DYNAMICALLY FROM A RESOURCE
 
Imports System.Drawing.Text
Imports System.Runtime.InteropServices
 
Module CustomFont
 
    'PRIVATE FONT COLLECTION TO HOLD THE DYNAMIC FONT
    Private _pfc As PrivateFontCollection = Nothing
 
 
    Public ReadOnly Property GetInstance(ByVal Size As Single, _
                                         ByVal style As FontStyle) As Font
        Get
            'IF THIS IS THE FIRST TIME GETTING AN INSTANCE
            'LOAD THE FONT FROM RESOURCES
            If _pfc Is Nothing Then LoadFont()
 
            'RETURN A NEW FONT OBJECT BASED ON THE SIZE AND STYLE PASSED IN
            Return New Font(_pfc.Families(0), Size, style)
 
        End Get
    End Property
 
    Private Sub LoadFont()
        Try
            'INIT THE FONT COLLECTION
            _pfc = New PrivateFontCollection
 
            'LOAD MEMORY POINTER FOR FONT RESOURCE
            Dim fontMemPointer As IntPtr = _
                Marshal.AllocCoTaskMem( _
                My.Resources.DIGITALDREAMNARROW.Length)
 
            'COPY THE DATA TO THE MEMORY LOCATION
            Marshal.Copy(My.Resources.DIGITALDREAMNARROW, _
                         0, fontMemPointer, _
                         My.Resources.DIGITALDREAMNARROW.Length)
 
            'LOAD THE MEMORY FONT INTO THE PRIVATE FONT COLLECTION
            _pfc.AddMemoryFont(fontMemPointer, _
                               My.Resources.DIGITALDREAMNARROW.Length)
 
            'FREE UNSAFE MEMORY
            Marshal.FreeCoTaskMem(fontMemPointer)
        Catch ex As Exception
            'ERROR LOADING FONT. HANDLE EXCEPTION HERE
        End Try
 
    End Sub
 
End Module

It is pretty straight forward, and the code has comments so you can see what is going on.

Then in the form, when the button is clicked, we make a single call to the module's GetInstance method to return the font.

    Private Sub Button1_Click(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs) _
                              Handles Button1.Click
 
        Label1.Font = CustomFont.GetInstance(12, FontStyle.Bold)
 
    End Sub

IMPORTANT: One key thing to note here, is that on the control you want to set this custom font on, you will need to set the UseCompatibleTextRendering property to true (the default is false). If you don't want to do this for some reason, then another method you can do is to use the given controls Paint event and custom draw the text using the custom font. However this is generally less ideal because not all controls fire paint events without tweaking them, and even some that do would put the burden on drawing the entire control in your hands. So setting UseCompatibleTextRendering to true is the easier route to go.

That is all there is to it. You can modify this to meet the specific needs of your application. Below is a link to download the WinForms application (VS2008) that contains the code (and font) used in this article.

VB.NET How to tell if a user can elevate to admin rights in Vista and Windows 7

Matthew Kleinwaks — Wed, 29 Jul 2009 19:20:00 GMT

Generally finding out if a user has the permissions to do something involves trying to do that thing, and handling the access denied (error 5) exception that results.

What if you wanted to know if a user is an admin though prior to doing some admin task via code? Normally this would be as easy as checking if the user is a member of the built in administrators group in Windows, however with Vista and Windows 7, the OS uses a split token so your user account runs with standard user permissions, but can elevate as needed to full admin rights.

When a standard user does the same thing, and invokes some process that requires administrative rights, they will be prompted with a user id/password dialog, and must enter the credentials of an account that is an admin member on the system.

My reason for having to look at this was due to a program where a process running as a standard user downloads some update files to the user's temp folder, and then launches an application as administrator to process those files. If the standard user gets a credentials dialog, and enters in alternate admin credentials, then the user profile changes, and the temp directory is now the admins temp directory, not the standard user's. This created lots of problems, and while there were a few options for a resolution, most were going to be messy, and I opted to go for the following approach:

When the user goes to download update files from the software, determine if they are an admin, and if not, determine if they CAN be an admin. If they can, then I know they will get the regular click through elevation prompt, and the profile will remain the same. However if they are not an admin, and they can not elevate to an admin, I can void the download, and inform the user the main download process should be invoked by an administrator. This will cause the temp files to be in the correct place, as well as some other environment variables that the program uses, and the update will succeed.

So that was my reason for needing it, but I know that several other reasons could exist for wanting to know if a Vista/7 user is an admin, but not running currently as one.

Ok so you probably came here for code and not to listen to my coding issues, so lets get down to it.

Here is the entire class file. It consists of just a few API calls, as well as 3 public functions for you to consume.

IsRunningAsAdmin(): Does the standard check to simply determine if the user is in the administrators group. Will return false for admins running the process with reduced rights in Vista/7.
CanElevateToAdmin(): Uses the Windows API calls to determine if the user can elevate, or is elevated currently.
RunningStandardButCanElevate(): Just a combination of the two above methods, as a shortcut to determine if the user can elevate to admin, but currently is not.

As you can probably tell by the method names, they are all boolean methods.

One thing to note, is that the CanElevateToAdmin method will check the OS version, and only do the API calls when the major version is greater than 5. (5 being Windows XP, 6+ being Vista and up) Otherwise it simply does the standard admin check.

Sometimes the code formatting may look a little odd, it is just to avoid weird wrapping in the blog post.

Imports System.Runtime.InteropServices
 
Class AdminCheck
 
#Region "CONSTANTS"
    Const TOKEN_QUERY As UInt32 = &H8
    Const INT_SIZE As Integer = 4
#End Region
 
#Region "ENUMERATIONS"
 
    Private Enum TOKEN_ELEVATION_TYPE
        TokenElevationTypeDefault = 1
        TokenElevationTypeFull
        TokenElevationTypeLimited
    End Enum
 
    Private Enum TOKEN_INFO_CLASS
        TokenUser = 1
        TokenGroups
        TokenPrivileges
        TokenOwner
        TokenPrimaryGroup
        TokenDefaultDacl
        TokenSource
        TokenType
        TokenImpersonationLevel
        TokenStatistics
        TokenRestrictedSids
        TokenSessionId
        TokenGroupsAndPrivileges
        TokenSessionReference
        TokenSandBoxInert
        TokenAuditPolicy
        TokenOrigin
        TokenElevationType
        TokenLinkedToken
        TokenElevation
        TokenHasRestrictions
        TokenAccessInformation
        TokenVirtualizationAllowed
        TokenVirtualizationEnabled
        TokenIntegrityLevel
        TokenUIAccess
        TokenMandatoryPolicy
        TokenLogonSid
        MaxTokenInfoClass
        ' MaxTokenInfoClass should always be the last enum
    End Enum
 
#End Region
 
#Region "WIN API FUNCTIONS"
 
    <DllImport("kernel32.dll")> _
    Private Shared Function GetCurrentProcess() As IntPtr
    End Function
 
    <DllImport("advapi32.dll", SetLastError:=True)> _
    Private Shared Function OpenProcessToken(ByVal ProcessHandle As IntPtr, _
                                            ByVal DesiredAccess As UInt32, _
                                            ByRef TokenHandle As IntPtr) As Boolean
    End Function
 
    <DllImport("advapi32.dll", SetLastError:=True)> _
    Private Shared Function GetTokenInformation( _
                            ByVal TokenHandle As IntPtr, _
                            ByVal TokenInformationClass As TOKEN_INFO_CLASS, _
                            ByVal TokenInformation As IntPtr, _
                            ByVal TokenInformationLength As Integer, _
                            ByRef ReturnLength As UInteger) As Boolean
    End Function
 
#End Region
 
#Region "PUBLIC METHODS"
 
    ''' <summary>
    ''' RETURNS TRUE WHEN THE CURRENT USER IS A MEMBER OF THE 
    ''' ADMINISTRATORS GROUP AND IS ALSO RUNNING THE PROCESS 
    ''' ELEVATED AS AN ADMINISTRATOR, OTHERWISE RETURNS FALSE.
    ''' </summary>
    ''' <returns>Boolean</returns>
    Public Shared Function IsRunningAsAdmin() As Boolean
 
        Return My.User.IsInRole(ApplicationServices.BuiltInRole.Administrator)
 
    End Function
 
    ''' <summary>
    ''' RETURNS TRUE WHEN THE CURRENT USER CAN ELEVATE TO ADMINISTRATOR RIGHTS
    ''' OR ALREADY HAD ELEVATED TO ADMINISTRATOR RIGHTS,
    ''' OTHERWISE RETURNS FALSE
    ''' </summary>
    ''' <returns>Boolean</returns>
    Public Shared Function CanElevateToAdmin() As Boolean
 
        'DETERMINE IF THE CURRENT USER IS ALREADY RUNNING WITH ADMIN RIGHTS
        Dim IsAdmin = IsRunningAsAdmin()
 
        'EXIT OUT NOW IF THE USER IS AN ADMIN, RETURNING TRUE
        'THERE IS NO ELEVATION NEEDED IF THE USER IS ALREADY 
        'RUNNING WITH ADMIN RIGHTS
        If IsAdmin Then Return True
 
        'IF VISTA OR HIGHER, CHECK FOR SPLIT TOKEN
        If Environment.OSVersion.Version.Major > 5 Then
            Try
                Dim myToken As IntPtr
                Dim elevationType As TOKEN_ELEVATION_TYPE
                Dim dwSize As UInteger
                Dim pElevationType As IntPtr = Marshal.AllocHGlobal(INT_SIZE)
 
                'GET A TOKEN REFERENCE FOR THE USER RUNNING THIS PROCESS
                OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, myToken)
 
                'GET THE ELEVATION INFORMATION FOR THIS TOKEN
                GetTokenInformation(myToken, _
                                    TOKEN_INFO_CLASS.TokenElevationType, _
                                    pElevationType, _
                                    INT_SIZE, _
                                    dwSize)
 
                'CAST THE RESULT TO ENUM TYPE
                elevationType = DirectCast( _
                                Marshal.ReadInt32(pElevationType),  _
                                TOKEN_ELEVATION_TYPE)
 
                'FREE ALLOCATED UNMANAGED MEMORY
                Marshal.FreeHGlobal(pElevationType)
 
                'DETERMINE THE RESULT OF THE ELEVATION CHECK
                '==============================================
                'TokenElevationTypeFull - User has a split token, 
                'and the process is running elevated
 
                'TokenElevationTypeLimited - User has a split token, 
                'but the process is not running elevated
 
                'TokenElevationTypeDefault - User is not using a split token
                '==============================================
                Return (elevationType = _
                        TOKEN_ELEVATION_TYPE.TokenElevationTypeLimited) OrElse _
                       (elevationType = _
                        TOKEN_ELEVATION_TYPE.TokenElevationTypeFull)
 
            Catch ex As Exception
                'LOG/HANDLE ERROR
                'RETURN FALSE IN EVENT OF ERROR
                Return False
            End Try
        Else
            'PRIOR TO VISTA, ONLY CHECK
            'NEEDED IS IF THE USER IS IN THE ADMIN GROUP
            Return IsAdmin
        End If
 
    End Function
 
    ''' <summary>
    ''' RETURNS TRUE WHEN USER IS RUNNING AS A STANDARD USER CURRENTLY
    ''' BUT CAN ELEVATE TO ADMIN RIGHTS WITH THEIR OWN CREDENTIALS
    ''' OTHERWISE RETURNS FALSE
    ''' </summary>
    ''' <returns>Boolean</returns>
    Public Shared Function RunningStandardButCanElevate() As Boolean
        Return CanElevateToAdmin() And (Not IsRunningAsAdmin())
    End Function
 
#End Region
 
End Class

Hopefully this will come in handy for anyone else that may be looking to determine this information. I did a good amount of searching around the web, and wasn't able to find a good example of this, especially in Visual Basic.

Thanks to Rob Teixeira for pointing me to GetTokenInformation API function, which enabled me to ultimately solve this issue.

SSL testing certificate and the .NET Framework

Matthew Kleinwaks — Mon, 13 Jul 2009 19:57:00 GMT

I was faced with an odd problem today. I needed to test an update for an application that is already in production. Normally this would be pretty simple to do in a staging environment of some sort, but that is what made this task different. There was none.

Basically what I was given was an application to install (no source code) and information on where it downloads its updates from. It did the downloading using a WebClient and calls over HTTPS to a directory on an IIS webserver that doesn't have anonymous access on. So the WebClient passes credentials as well over HTTPS to authenticate. The URLS were hard coded in the app, so I had no way to redirect them somewhere other than the live server, and that was what made this problem interesting.

I had to get a little clever and get in MacGyver mode since this was going to take a good amount of mucking around with the system itself. Since this was just for testing, I didn't mind screwing up the testbox, which was just a virtual machine anyway.

My first issue was how to I redirect hard coded URLS that point to https://www.somedomain.com/ to my local IIS server where I had a local mirror of the update site's contents. I ended up using the HOSTS file in Windows to accomplish this. Basically if you don't know what the HOSTS file is, it is a file (located at %systemroot%\system32\drivers\etc\ on most Windows versions) that is a list of manual DNS resolutions at the machine level. Opening it will show you a single DNS resolution for localhost, which points to the system loopback of 127.0.0.1.

I added an entry for the customers domain and the IP address of my local IIS server so it looked something like this:
192.168.1.145 www.somedomain.com

This made the testbox redirect to my local IIS IP address whenever a request was made for the actual domain.

Ok so problem solved with redirecting the traffic, however at this point I was not aware that the calls were made over HTTPS. I soon found that out as the tests were failing because my local IIS had no SSL installed on it.

Looking around for a way to make a testing certificate sounded like it was going to be somewhat of a process, even using some free tools like OpenSSL to create a self signed certificate for my testing purposes. Luckily I found a free download from Microsoft IIS resource kit (thanks to a tip from Maurice de Beijer). It is geared towards IIS6, however it will install and at least do what is need for this task at least on XP Professional with IIS 5.1, which is what I was using for my testing server.

Installing this resource kit gives you an entry in your start menu for IIS Resources -> SelfSSL.

This little command line utility will easily create and install a self signed certificate into IIS on the machine.

So all done right? Well not exactly, this is where things got even more complicated.

So over to my testbox, I was able to connect to my local IIS when I type their domain in my browser due to the HOSTS file modification, however any requests for HTTPS versus HTTP would make IE yell foul that the cert doesn't match the domain, and also it was not trusted or signed by a CA, which of course is true, it was signed by me .

To fix this for IE I just needed to go into advanced options and uncheck the box to "warn about certificate address mismatch". I also needed to continue through the IE warning and view the site. I clicked on the red cert error box once I was on the site, and selected to install the certificate to the machine. After doing these 2 steps, Internet Explorer worked just as it would if it was a legit signed cert from a legit CA. I imagine an alternative to this method would be to export the cert to a .cer file from the IIS box, and then copy it over to the testbox and import it manually using the certificates MMC snapin.

So all done right? Nope.

So at this point I figured I was all done and was patting myself on the back for a job well done. Until I tried to actually run their app and deliver the update to it from my local IIS server. It just wouldn't connect, and while it didn't crash because of the exception handling in the application, it simply acted as if it could not find the internet site it was trying to.

Examining some log files showed me the error was specifically this:
"The underlying connection is closed: Could not establish trust relationship for the ssl/tls secure channel"

With an inner exception message of:
"The remote certificate is invalid according to the validation procedure"

At this point I tried everything. I imported the self signed certificate into every possible store I could, I added the MMC snapin for certificates and added the cert to all levels in there (machine and user level). Simply nothing worked at all, I always would get the same error.

Searching for information on this topic brings up mainly one answer, which is to use some code to custom validate certificates, and always return true. This would have been very easy, if I had the actual source code to work with, and not just a compiled application. If you do have that luxory, then this is the code you would use:

Imports System.Net
Imports System.Net.Security
Imports System.Security.Cryptography.X509Certificates
 
    Private Shared Function customCertValidation(ByVal sender As Object, _
                                                ByVal cert As X509Certificate, _
                                                ByVal chain As X509Chain, _
                                                ByVal errors As SslPolicyErrors) As Boolean
        Return True
    End Function
 
    'USAGE
    Public Sub DoStuff()
        'CALL THIS BEFORE ANY HTTPS CALLS THAT WILL FAIL WITH CERT ERROR
        ServicePointManager.ServerCertificateValidationCallback = _
            New System.Net.Security.RemoteCertificateValidationCallback(AddressOf customCertValidation)
        '
        '
        '
    End Sub

Note that you don't have to simply return true, you can do whatever type of cert validation you want, and only return true under the conditions you want. Simply returning true and doing nothing else just says we don't care about any of the cert details, just allow it.

I was getting ready to admit defeat here, as it just did not look like there was a way to do this with a compiled application. I even tried sifting through the various .NET config files like machine.config and security.config looking for something. It just was baffling me that I could add this cert to my trusted stores and IE was happy with that, but .NET was not. Then I came across some information about ServicePointManager in an application config file. This sounded interesting as if it would work, it would be something I could add to the existing application without needing to do anything with the binaries themselves.

I added the following XML to the app.config file, and sure enough, it worked like a charm.

  <system.net>
    <settings>
    <servicePointManager
        checkCertificateName="false"
        />
    </settings>
  </system.net>

So to recap what I did to get this all working:

Edited HOSTS file on testbox to redirect URLs for a specific domain to my local IIS server
Installed a self signed SSL cert on my IIS server using IIS Resource Kit SelfSSL utility
Turned off option to warn about cert name mismatches in IE
Navigated to HTTPS site in IE, got cert error
Continued through and then clicked on red cert error and selected to install certificate to the local test machine
Added config file (or append existing config file) with the above ServicePointManager settings, to not check cert names.

After this, everything worked great, and my IIS acted just like their live server, and the app did not know the difference.

Hopefully if someone comes across a similar issue, this may help them out.

.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.

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.

VB.NET : Translucent Controls in Windows Forms (Part Deux)

Matthew Kleinwaks — Tue, 06 May 2008 12:14:00 GMT

So yesterday I talked about making a translucent button in WinForms using VB.NET. If you have not read that yet, then you should probably do so before digging into part 2, where we expand part 1 to cover more controls.

Today lets look at making a translucent TabPage control.

Here is our end result:

So we have a nice cherry sunburst Gibson Les Paul as our form background, with a TabControl overlaying it, with a few buttons on it.

So what is different about the implementation of the translucent tab control versus the buttons we did last time? Well for starters, the translucent painting of the background needs to be done on the TabPages which are the individual tab objects that the TabControl contains.

I am not going to redefine all the code used for this control, as much of it is the same as from the button control. The full source of the project is attached to this post, so you can download that for all the code.

I will go over the specific differences between the button and the TabControl so you can see what we had to do differently.

The first thing is, we want to make the control translucent regardless of what tab is currently selected. So we need to track controls being added or removed from the TabControl. TabControls can ONLY have TabPages added to their controls collection, otherwise the framework throws an error. So we wire up the OnControlAdded and OnControlRemoved event handlers to add or remove the given TabPage from being custom drawn as translucent.

#Region "OVERRIDES TO HANDLE CHILD TABPAGES"
    Protected Overrides Sub OnControlAdded( _
              ByVal e As System.Windows.Forms.ControlEventArgs)
 
        AddHandler DirectCast(e.Control, TabPage).Paint, _
                   AddressOf DrawFormBackgroundOnTabPage
 
        MyBase.OnControlAdded(e)
    End Sub
 
    Protected Overrides Sub OnControlRemoved( _
              ByVal e As System.Windows.Forms.ControlEventArgs)
 
        RemoveHandler DirectCast(e.Control, TabPage).Paint, _
                      AddressOf DrawFormBackgroundOnTabPage
 
        MyBase.OnControlRemoved(e)
    End Sub
#End Region

Note the DrawFormBackgroundOnTabPage method we are wiring up. We will define that next.

#Region "CUSTOM PAINTING ROUTINE"
    Private Sub DrawFormBackgroundOnTabPage(ByVal sender As Object, _
                                            ByVal e As PaintEventArgs)
 
        'DON'T DO ANY CUSTOM PAINTING IF THE FEATURE IS DISABLED
        If Not _isTranslucent Then Return
 
        Dim myTab As TabPage = DirectCast(sender, TabPage)
 
        'GET THE CONTROL THAT THE IMAGE IS ON WE WANT TO USE FOR TRANSLUCENCY
        Dim parentControl As Control = Nothing
        If _backgroundImageSource = _
           ITranslucentControl.eBackgroundImageSource.Form Then
            'GET FORM
            parentControl = Me.FindForm
        Else
            'GET PARENT (WILL BE FORM IF NO CONTAINER EXISTS)
            parentControl = Me.Parent
        End If
 
        'IF THE PARENT CONTROL WE ARE REFERNCING HAS NO 
        'BACKGROUND IMAGE, DO NOTHING
        'ALSO CHECK TO MAKE SURE STRETCH IS THE LAYOUT TYPE
        If parentControl.BackgroundImage Is Nothing Then Return
        If parentControl.BackgroundImageLayout <> _
           ImageLayout.Stretch Then Return
 
        'SOURCE RECTANGLE IS THE CLIPPED REGION OF THE 
        'FORMS BACKGROUND IMAGE THAT IS BEHIND THE TABPAGE. 
        'CLIPPING ALLOWS US TO THEN PASTE THE COVERED PART
        'OF THE FORM BACKGROUND IMAGE ONTO THE LISTVIEW 
        'BACKGROUND TO MIMIC TRANSPARENCY
        Dim srcRect As Rectangle = Nothing
 
 
 
        If _backgroundImageSource = _
           ITranslucentControl.eBackgroundImageSource.Form Then
            srcRect = New Rectangle(GetPointFromForm(myTab), myTab.Size)
        Else
            srcRect = New Rectangle( _
                                  (myTab.Left + Me.Left), _
                                  (myTab.Top + Me.Top), _
                                  myTab.ClientRectangle.Width, _
                                  myTab.ClientRectangle.Height)
        End If
 
        'IMAGE WITH THE CURRENT CLIENT SIZE OF THE BACKGROUND
        Dim mySourceImage As New Bitmap(parentControl.BackgroundImage, _
                                        parentControl.ClientSize.Width, _
                                        parentControl.ClientSize.Height)
 
        'IMAGE ATTRIBUTES SO WE CAN SET GAMMA (TO MAKE IMAGE LIGHTER)
        Dim image_attr As New Drawing.Imaging.ImageAttributes
        image_attr.SetGamma(_gamma)
 
        'DRAW THE CROPPED IMAGE ONTO THE TABPAGE
        e.Graphics.DrawImage(mySourceImage, _
                            myTab.ClientRectangle, _
                            (srcRect.X + _Offset.X), _
                            (srcRect.Y + _Offset.Y), _
                            srcRect.Width, _
                            srcRect.Height, _
                            GraphicsUnit.Pixel, _
                            image_attr)
 
        image_attr.Dispose()
        image_attr = Nothing
 
 
    End Sub
#End Region

The concept we use is the same as the buttons, however sender is always going to be a TabPage, so we grab that at the start of the routine, and use it as our painting canvas. The key difference is we actually paint the background onto the TabPage, where as the button got its backgroundimage property assigned to the image we wanted to show. There is also a little bit of additional positioning code, to account for the parent of the TabPage, which is the containing TabControl. Since the TabControl has the actual tabs on it, we need to take that into account, otherwise the section of the background we grab to paint on the tabs will be badly offset.

Remember for a full rundown, read part 1: Translucent Button in WinForms

As always, send me your comments or code improvements if you happen to find any.

VB.NET : Translucent Controls in Windows Forms

Matthew Kleinwaks — Mon, 05 May 2008 17:44:00 GMT

Windows Forms controls in .NET do a lot more for us than they did in previous versions of VB. One of the best things about getting all the OO features .NET brought us, is the ability to extend controls through inheritance or some other means. Some controls directly support custom drawing of their visuals, while others need to be extended to do so.

One thing I have seen asked a few times, was how to make a given control translucent, which I like to think of a little differently than transparent.

So after some investigation, I came up with a method that works decently to do this for most standard WinForm controls you would want to do this with. The biggest issues I came across, were dealing with scrolling and the custom drawing, which I am still looking at for controls that scroll. However some controls do not, like a button, and that is what we are going to take a look at today.

The idea of translucent controls really revolves around the concept that your WinForm is going to have an image as its background. It also assumes this image is set to stretch so that the image takes up the entire form background. The code in this example can be tweaked if this is not your exact scenario, as this is more or less a proof of concept on doing things this way.

So first let me explain the concept we are going for by illustrating the end result:

You can see we have a standard button just to pair against the custom button. Then a custom button that looks the same because its IsTranslucent property (one of the custom properties we add to the button) is set to false. The two bottom buttons have IsTranslucent set to true, and the left button has the default gamma setting of 1.0, while the one on the right has a frosted effect by settings its gamma to 0.15.

So now lets talk about how we actually do this.

The first thing I did was identify the common elements to a translucent control. I found that (for now) they are:

Background Source - where are we getting the background from to paint onto the button
Gamma - value to indicate the over/under saturation of the image to give it a frosted or darkened effect
IsTranslucent - indicates if the control should be translucent at all. When this is false, all the custom code is skipped, and the control behaves like a normal button
Offset - Since controls often have borders and a 3D look, this property allows an offset of the painted image so it perfectly matches with the background of the form/container. Buttons I found work well with an offset of 5/5, while other controls needed no offset, because they appear flat already.

So because all controls that I want to make translucent will use these features, I created an interface that the controls can implement.

Lets define that interface now:

Public Interface ITranslucentControl
 
    Enum eBackgroundImageSource
        Form = 0
        Container = 1
    End Enum
 
    Property Gamma() As Single
    Property IsTranslucent() As Boolean
    Property Offset() As System.Drawing.Point
    Property BackgroundImageSource() As eBackgroundImageSource
End Interface

Pretty straight forward, it has all the things I described in the bullet points above. If you are not familiar with interfaces, then all you should really know, is that our custom button will implement this interface, which means it will have all these properties in itself, however the actual code in these properties is totally up to the class to implement. Most of these properties simply access backing fields in the class though. There is no real magic going on here, I just made the interface because I know all my custom translucent controls will use these items, but inheritance from a base class was not really an option because we need to inherit from the control we want to extend. So if you are wondering "Couldn't I do this without the interface?" the answer is yes, I just decided to use one so I wouldn't forget any of the common properties I want the control to have.

Ok, so now that we have our interface, we need to make our button class.

Imports System.Windows.Forms
Imports System.Drawing
 
Public Class TranslucentButton
    Inherits System.Windows.Forms.Button
    Implements ITranslucentControl
 
End Class

So our class name is TranslucentButton, and it inherits from button and implement our ITranslucentControl interface.

Lets add a constructor which sets double buffering to true. This can reduce flicker where possible, which is a common issue for WinForms and graphics.

#Region "CONSTRUCTOR(S)" 
Public Sub New()
        'SET DOUBLE BUFFERING TO REDUCE FLICKER WHERE POSSIBLE
        MyBase.DoubleBuffered = True
    End Sub
#End Region 

You will note I make use of code regions to keep things separated and easy to manage in the code window.

Next we have all the public properties which came from the ITranslucentControl interface, along with backing private fields to maintain the state of the object. Interfaces can't define fields, so we need to manually do that in each one.

#Region "PUBLIC PROPERTIES AND ASSOCIATED PRIVATE FIELDS"
 
    Private _gamma As Single = 1.0
    ''' <summary>
    ''' Gets or Sets the gamma correction to
    ''' use for the translucent image background
    ''' </summary>
    ''' <value>Single</value>
    ''' <returns>Value (as single) for the gamma correction</returns>
    ''' <remarks>None</remarks>
    Public Property Gamma() As Single _
                            Implements ITranslucentControl.Gamma
        Get
            Return _gamma
        End Get
        Set(ByVal value As Single)
            If value < 0.01 Then value = 0.01
            _gamma = value
        End Set
    End Property
 
    Private _isTranslucent As Boolean = False
    ''' <summary>
    ''' Indicates if control will be drawn translucent. False by default.
    ''' </summary>
    ''' <value>Boolean</value>
    ''' <returns>True if control is translucent, otherwise False.</returns>
    ''' <remarks>None</remarks>
    Public Property IsTranslucent() As Boolean _
                              Implements ITranslucentControl.IsTranslucent
        Get
            Return _isTranslucent
        End Get
        Set(ByVal value As Boolean)
            If value <> _isTranslucent AndAlso value = False Then
                Me.BackgroundImage.Dispose()
                Me.BackgroundImage = Nothing
            End If
            _isTranslucent = value
        End Set
    End Property
 
    Private _Offset As New Point(5, 5)
    ''' <summary>
    ''' Provides an offset value incase the image is 
    ''' not correctly aligning in this control. 
    ''' This can occur when special using a 3d border, 
    ''' or something similar that would cause an offset
    ''' </summary>
    ''' <value>Point. Default value is 5, 5 for this control</value>
    ''' <returns>
    ''' Current offset for this controls background drawing
    '''</returns>
    ''' <remarks>None</remarks>
    Public Property Offset() _
                    As Point _
                    Implements ITranslucentControl.Offset
        Get
            Return _Offset
        End Get
        Set(ByVal value As Point)
            _Offset = value
        End Set
    End Property
 
    Private _backgroundImageSource As _
            ITranslucentControl.eBackgroundImageSource = _
            ITranslucentControl.eBackgroundImageSource.Form
    ''' <summary>
    ''' Gets/Sets the source of the background image for this control
    ''' </summary>
    ''' <value>eBackgroundImageSource enumeration value</value>
    ''' <returns>
    ''' eBackgroundImageSource.Form when the forms 
    ''' background should be used, eBackgroundImageSource.Parent
    ''' when the forms immediate parent should be used
    ''' </returns>
    ''' <remarks>
    ''' This setting is ignored when
    ''' IsTranslucent is False
    ''' </remarks>
    Public Property BackgroundImageSource() As _
                    ITranslucentControl.eBackgroundImageSource _
                    Implements ITranslucentControl.BackgroundImageSource
        Get
            Return _backgroundImageSource
        End Get
        Set(ByVal value As ITranslucentControl.eBackgroundImageSource)
            _backgroundImageSource = value
        End Set
    End Property
 
#End Region

This looks like a lot of code, but all it is, is each of the implemented properties from our interface, along with a backing field. There is a decent amount of comments too. You could add some validation to the properties if you wanted, lets say, to limit the gamma value.

We use one private field here that is not part of the interface, and it is also not exposed via a public property. It is called _bypassPainting and it is just a boolean flag we set to skip the paint event of the control from firing twice, which would affect performance.

#Region "PRIVATE FIELDS"
    'FLAG USED TO BYPASS REPAINTING AFTER THE BACKGROUND PICTURE IS SET
    Private _bypassPainting As Boolean = False
#End Region

So that is the entire class, with the exception of the paint event which does all the hard work. Time to dig into that one and see where the "magic" happens.

So the magic that happens, is actually that the button looks at its parent control, which may be a form, or it may be another container, such as a groupbox or panel. You may want to have a button in a panel, but still have it use the forms background image for its translucency. Or maybe you do actually want the panels background image to be the image we see through the button. This is why we have the BackgroundImageSource property, which if you remember is an enum value of Form or Container. This value does not matter at all if the button is directly on the form to begin with. It only comes into play when the button is in an additional container.

The button takes the image should be seen through the button, and calculates which part of this image the button is actually covering. It then takes that region of the image, and creates a new image from that, and uses that as the buttons background image. This gives the button its transparent look, but still gives it all the standard features of a button. From there you can set gamma to make the image in the button lighter or darker if needed. I made the default offset of the button 5,5 which takes into account the buttons 3D appearance. This can be customized in the event the images are not matching perfectly between the parent image and the button image.

I won't go into too much more detail about the paint event, as it is commented pretty well, and if you follow it along, should be self explanatory.

#Region "CUSTOM PAINTING ROUTINE"
    Protected Overrides Sub OnPaint( _
        ByVal pevent As System.Windows.Forms.PaintEventArgs)
        MyBase.OnPaint(pevent)
 
        'IF BYPASSPAINTING FLAG WAS SET, RESET IT AND DO NOT PAINT
        If _bypassPainting Then
            _bypassPainting = False
            Return
        End If
 
        'DON'T DO ANY CUSTOM PAINTING IF THE FEATURE IS DISABLED
        If Not _isTranslucent Then Return
 
        'GET THE CONTROL THAT THE IMAGE 
        'IS ON WE WANT TO USE FOR TRANSLUCENCY
        Dim parentControl As Control = Nothing
        If _backgroundImageSource = _
           ITranslucentControl.eBackgroundImageSource.Form Then
            'GET FORM
            parentControl = Me.FindForm
        Else
            'GET PARENT (WILL BE FORM IF NO CONTAINER EXISTS)
            parentControl = Me.Parent
        End If
 
        'IF THE PARENT CONTROL WE ARE REFERENCING 
        'HAS NO BACKGROUND IMAGE, DO NOTHING
        'ALSO CHECK TO MAKE SURE STRETCH IS THE LAYOUT TYPE
        If parentControl.BackgroundImage Is Nothing Then Return
        If parentControl.BackgroundImageLayout <> _
           ImageLayout.Stretch Then Return
 
        'SOURCE RECTANGLE IS THE CLIPPED REGION 
        'OF THE FORMS BACKGROUND IMAGE
        'THAT IS BEHIND THE TABPAGE. CLIPPING ALLOWS 
        'US TO THEN PASTE THE COVERED PART
        'OF THE FORM BACKGROUND IMAGE ONTO
        'THE LISTVIEW BACKGROUND TO MIMIC TRANSPARENCY
        Dim srcRect As Rectangle = Nothing
 
        If _backgroundImageSource = _
           ITranslucentControl.eBackgroundImageSource.Form Then
            srcRect = New Rectangle(GetPointFromForm(Me), Me.Size)
        Else
            srcRect = Me.Bounds
        End If
 
        'IMAGE WITH THE CURRENT CLIENT SIZE OF THE BACKGROUND
        Dim mySourceImage As New Bitmap(parentControl.BackgroundImage, _
                                        parentControl.ClientSize.Width, _
                                        parentControl.ClientSize.Height)
 
        'BLANK IMAGE WE WANT TO DRAW THE 
        'SECTION TO THAT WE WILL DISPLAY IN THE LISTVIEW
        Dim myButtonImage As New Bitmap(srcRect.Width, srcRect.Height)
 
        'CREATE A GRAPHICS OBJECT FROM THE IMAGE
        Dim g As Graphics = Graphics.FromImage(myButtonImage)
 
        'IMAGE ATTRIBUTES SO WE CAN SET GAMMA (TO MAKE IMAGE LIGHTER)
        Dim image_attr As New Drawing.Imaging.ImageAttributes
        image_attr.SetGamma(_gamma)
 
        'DRAW CROPPED AND LIGHTENED IMAGE TO 
        'THE GRAPHICS OBJECT (WRITES TO myListViewImage OBJECT)
        g.DrawImage(mySourceImage, _
                    Me.ClientRectangle, _
                    (srcRect.X + _Offset.X), _
                    (srcRect.Y + _Offset.Y), _
                    srcRect.Width, _
                    srcRect.Height, _
                    GraphicsUnit.Pixel, _
                    image_attr)
 
        image_attr.Dispose()
        g.Dispose()
        image_attr = Nothing
        g = Nothing
 
        'BEFORE WE SET THE BACKGROUND IMAGE, SET THE BYPASS FLAG
        'SO WE DONT GET STUCK IN A PAINTING LOOP
        _bypassPainting = True
 
        Me.BackgroundImageLayout = ImageLayout.None
        Me.BackgroundImage = myButtonImage
 
    End Sub
#End Region

There is one other method we use for support here, and it gets the location of the button in relation to the form when the button is not directly on the form (it is in a container or multiple containers on the form)

#Region "SUPPORT METHODS"
    Private Function GetPointFromForm(ByVal C As Control) As Point
        Try
            Return C.FindForm.PointToClient( _
                   C.Parent.PointToScreen(C.Location))
        Catch ex As Exception
            Return New Point(0, 0)
        End Try
    End Function
#End Region

So that is it. Above is all the code you need to get this working, and you can find the source code attached to this post. It was written in Visual Studio 2008, however for maximum compatibility, it is targeting the .NET 2.0 framework since this doesn't use any 3.x exclusive features. That also means you could copy/paste this code into Visual Studio 2005 and it would also work.

One last note I want to touch on again, is that this is just a proof of concept, and has not been fully tested on all operating systems and under various different settings and configurations you may have on your WinForm. That being said, most likely you can modify this code to meet your needs.

Next time I will show you how to do this same thing, but with specific container controls, such as the GroupBox, Panel, and TabControl. I also have done this with the label control. The label support transparent backgrounds right out of the box, however adding my method adds the ability for the frosted effect, as well as the ability to target a parent form, instead of just the label container.

As always, send me your comments or code improvements if you happen to find any.