Application.EnableVisualStyles

In Windows XP, the concept of Visual Styles was introduced to allow customization of the look and feel of windows and controls. Most applications that target Windows XP and above will want to take advantage of Visual Styles. In v1.1 of the .NET Framework, we added a way to programmatically enable visual styles in Windows Forms applications. Most .NET developers are most likely already familiar with the Application.EnableVisualStyles method. The purpose of this blog, therefore, is not to introduce this method, but to explain a little bit about what it actually does. I will also attempt to address frequently asked questions regarding this method. The rest of this post is in the form of an FAQ.

(Update: Most of the issues mentioned below are fixed in .NET Framework 2.0 (Whidbey). There are also a bunch of improvements in Visual Styles support in Windows Forms. See this post for a summary of the new features.)

Q What does Application.EnableVisualStyles actually do?

Windows XP ships with two versions of the Common Controls Library (comctl32.dll) - versions 5.8 and 6.0. v5.8 renders controls in the "Classic" style that you get on Windows NT/2000 and Windows 9x. v6.0 renders controls using the XP Visual Styles look and feel. Since most Windows Forms controls are based on comctl32, how they are rendered depends on which version of comctl32 is used to do the rendering. By default, v5.8 is used to render the client area of the app and v6.0 is used to render the non-client area. That is why you see the title bar and window borders automatically render "themed", while the controls (like Button, TextBox, ListView, ComboBox and so on) have the classic look by default.

In v1.0 of the Framework, the way to get visual styles in a Windows Forms app was to ship a manifest file with the app, that has information in it to indicate that v6.0 of comctl32 should be used for rendering. While this works fine, many developers felt it cumbersome to author, maintain and deploy manifest files. They felt the need to be able to do this programmatically. Now, the Platform SDK does provide API to do this. Basically, you need to create and activate an Activation Context that has pretty much the same DLL redirection information in it as the manifest file. The Activation Context API can be used to do this in a way suitable to your application.

If you take a look at these API, you will probably notice that they aren't very easy to use. While the advanced developers may like to tinker around with activation contexts, it is probably not something a developer who wants some "quick and dirty" code to get visual styles will do. So the Windows Forms team decided to wrap these API and expose a simple method that developers could call, that would isolate them from these complexities. So, essentially, when you call Application.EnableVisualStyles, we set up an activation context around the application's message loop, so that comctl32 function calls can be properly redirected to comctl32 v6.0. That way, you don't need to include a manifest with your app.

Q Why should Application.EnableVisualStyles be called before Application.Run?

As mentioned above, the activation context that we create is setup around the application's message loop. When EnableVisualStyles is called, we set a flag to indicate that a context needs to be activated. This flag is used to determine whether the activation context code is called or not during message loop setup. Application.Run sets up the message loop, so naturally the call to EnableVisualStyles should precede it.

Q Why should I set the FlatStyle property of some controls to System to get the themed look and feel?

For those controls that have FlatStyle properties, in all modes except FlatStyle.System, Windows Forms custom-renders the controls. In v1.0 and v1.1, the Windows Forms rendering code is not "theme-aware", so EnableVisualStyles has no effect unless comctl32 itself does the rendering. The FlatStyle.System setting does exactly that - tells Windows Forms to allow comctl32 to render the control. Unfortunately, in this mode, cool features like setting the BackColor or assigning an image to the control do not work, since to support these, Windows Forms needs to do the rendering.

Q I wish FlatStyle.Standard would give me the themed look. That way, I could get the best of both worlds - themed look and feel as well as features like assigning a BackColor or image.

Agreed! We are planning to make our custom rendering code more theme-aware in a future version of the Framework.

Q Some Windows Forms controls don't get themed properly - for example, the TabControl's body has a grey background, which looks rather inconsistent and the NumericUpDown control's up and down buttons aren't themed.

Yes, this is again due to the fact that Windows Forms custom rendering, unfortunately, isn't currently theme-aware. We will try and fix this in a future version!

Q I sometimes have weird problems with Application.EnableVisualStyles. Some controls don't seem to pick up theming; images that are assigned to TreeView nodes or ListView items sometimes don't render at all. However, when I use a manifest, I don't see these problems.

Yes, this is a known issue with the implementation of Application.EnableVisualStyles. The reason for this is as follows. As I mentioned before, the activation context is setup around the application's message loop. So any comctl32 handles created after the message loop is setup will be correctly redirected to v6.0. However, when you have the following code in Main:

Application.EnableVisualStyles();
Application.Run(new Form1());

Form1 is constructed before the message loop is setup. Therefore, any handle created in Form1's constructor code will result in that control being bound to v5.8 instead of v6.0, since the activation context has not yet been setup. This isn't as bad as it may sound, since in most cases, we delay handle creation as much as possible, so control handles aren't typically created in InitializeComponent. One rather common exception is the Imagelist - it turns out that in many cases, the Imagelist's handle is created in InitializeComponent, so you get a v5.8 imagelist that doesn't interop well with v6.0 controls on XP (on Windows Server 2003, the v5.8 imagelist does interop well with v6.0 controls, so you won't see this problem on that platform), the result being that the images don't show up. There are also some cases where some other control handles may get created early, in which case, those controls too will get bound to v5.8 and will not appear themed. We are obviously planning to fix this in the future, but for now, there are several workarounds that customers have used successfully. I list some of them here for reference:

  • Include a call to Application.DoEvents() before Application.Run().
  • Move the erring code (that causes handle creation to happen) from InitializeComponent to the Form's Load method.
  • Use a manifest!

Note that the above discussion applies only to the app's "Main Form", i.e., the Form that is passed to the Application.Run. Forms that are instantiated after the message loop is setup will be constructed after the context is activated, so code in their constructors shouldn't face this problem.

Q I am writing a Windows Forms control and I wish to make use of Visual Styles to ensure that my control's look and feel is consistent with the rest of the application. How can I do this?

Currently, there are no managed classes in the Framework to do this. You will need to p/invoke and use the UxTheme API. These API give you the ability to render common control parts, get information about visual style recommended colors, find out if a visual style is active and so on.

As always, feel free to let me know if you need any more information about Visual Styles or have any suggestions!