XP Common Controls

Getting “That WinXP Look” with XP Common Controls

DISCLAIMER:
This documentation has been written back in 2006. A lot of things have changed since then and not all statements are still true. Especially when it comes to some of the basic functionality of the current Form controls in .NET 4.6.1. Some of the functionality provided by my controls back then are now to a certain extend part of the standard controls. So please check them first…
A Humble Request:
I can’t find the source code for the sample app referenced in this documentation. If you are one of the users that downloaded that code back in the day, can you please reach out to me and send me that source code so I can release it as part of this article?

How often have you tried to make your applications look like products from Microsoft, responding to customers’ wishes that they resemble Outlook, Word, or some other Microsoft application? Achieving that look can be difficult, though, because development products from Microsoft don’t traditionally include components that let developers create applications with “that WinXP look”.
You can solve this problem by using XP Common Controls (XPCC). XPCC provides controls that correspond to the definitions of Microsoft’s Windows XP Visual Guidelines (XPTaskBox, XPLetterBox, etc.) plus some controls that were incomplete in or absent from those guidelines (such as grouped list box and balloon tips).

Getting Started

XPCC requires version 1.1 or 2.0 of the .NET framework although it should also work if you’re developing with the Mono Framework as long as you don’t use any API-enhanced controls (discussed in the next section). Using Visual Studio for full design-time support is advisable.
You can donwload the full source code or just the compiled assembly from the download link at the project’s home page. If you download the full source code you must compile it and reference it in your solution (see the Appendix for instructions on how to add the controls to the toolbox in Visual Studio).
The download includes a sample application to help you better understand how to use the XPCC components. The application is a Windows Form styled after the Windows Explorer. It shows some of the controls in action. Simply start the app and click on any user. You can then enter any text into the password field (it won’t be checked) after which you will be transferred to the appilcation’s main window. At this point, select File -> Open and load the file Oscars.xml. You will see a list of all the Oscar winners with their categories and years displayed in the ListView.
This testbed application will be used as the example through the remainder of this article.

Using XP Common Controls

The controls that ship with XP Common Controls are split into three categories: Themed, API-Enhanced and Other. The following sections introduce some of the most frequently used controls in the package.
The Themed controls are probably the controls you’ll use most often for building apps with a Windows XP look and feel. They are designed as outlined in the Windows XP Visual Guidelines (http://www.microsoft.com/whdc/Resources/Windowsxp/default.mspx), including size, font, and color definitions. Every control has its own format definition and separate theming information that can be overridden in your form. This also means that the rendering of the controls does not rely on Windows XP. Instead the controls rely on GDI+ for their graphics-related functionality, so they will render the same way on any installation (Windows or other) that has the .NET framework installed. However, when an XPCC-enabled application is run on Windows XP, the XPCC controls will display in a style that matches the user’s current theme.

Rolling out new controls

A task box control is probably one of the most requested items in Visual Studio and it’s one of the main reasons i started this project. XPCC’s XPTaskBox control draws a task box as outlined in the design guidelines (except that its edges are all rounded – a tribute to Apple). It is a container control that allows you to host other controls inside it. It also supports expanding and collapsing, like its counterparts in Windows Explorer.
Unlike most other vendor implementations, the XPTaskBox is not just a list wrapper or grouping style but a full-fledged panel control that you can use like any other container on your form control.
A task box is best placed inside an XPTaskPanel, a panel control included in this library that supports theming and acts like the Windows Explorer sidebar. Each task box should be docked to the top of the panel to fully support the expanding and collapsing of multiple task boxes.
XPLetterBox and XPSoftBarrier are similar to the task box control. They also support theming and comply with Microsoft’s design guidelines.

Understanding Theming

All the controls in the Themed namespace allow you to do automatic and manual theming. Automatic theming is done through the ThemeListener class, which raises an event if you change the Windows XP theme. It also sets each themed control’s Theme property accordingly:

'This class listens to any changes in the UITheming and sets each  themed controls theming accordingly
Public WithEvents listener as New ThemeListener(Me)

You can manually oiverride this behaviour by setting each control’s Theme property by hand. If you do some manual theming (i.e. let the user decide what theme your window should have), you must iterate through all the controls that support theming and call the SetTheme() method on each control:

Private Sub SetAppearance(ByVal sender as System.Object, ByVal e as System.EventArgs) _
    Handles mnuBlue.Click, mnuOliveClick, mnuSilver.Click, mnuUnthemed.Click
    Dim th as ThemeStyle
    th = [Enum].Parse(GetType(ThemeStyle), CType(sender, MenuItem).Text)
    'recursively setting the theme on any control
    SetTheme(Me, th)
    End Theme
End Sub
Private Sub SetTheme(ByVal ctrl as Control, ByVal theme as ThemeStyle)
    If TypeOf ctrl Is IThemed Then
        CType(ctrl, IThemed).Theme = theme
    End If
    For Each c as Control in ctrl.Controls
       SetTheme(c, theme)
    Next
End Sub

Working with Provider Components

Provider Components are invisible objects that extend controls on a form. As the name implies, these components provide additional functionality without the need to subclass controls. Provider Components can be applied to a variety of controls or classes regardless of their type. I have found them to be the most convenient way to do custom rendering.
The XPCueBanner is an extender control that enables your text boxes to display help text inside empty text boxes. The text hints disappear as soon as any text is entered in the text box.
This is a convenient way to save UI space and combine labels and text boxes in one control. Simply drag the extender control to your Windows form and you will instantly have the additional property CuebannerText on every text box in your form. You can then set the cue text in the property box and it will be displayed in the text box as long as the text box is empty.
The CueBannerText property doesn’t appear in the Textbox class, so if you want to set it programatically you’ll need to tell the extender interface to add this property for you. In the following example the first parameter is the control to which you want to add the property and the second parameter is the corresponding value:

'CueProvide created by adding to design surface
Me.cueProvider.SetCueBanerText(me.txtYear, "Year")

Implementing list controls

XPCC has several diffent list controls that let you improve varrious aspects of lists in your applications.
XPListView allows you to group automatically by a column and display anyh column in the tile details view, which is still not supported in the standard ListView control.
Autogrouping by column value is very simply. Just tell the XPListView which column it should use and the control will create a group for every distinct column value and attache the etrnies to this column:

Private Const MOVIENAME_COLUMN as Integer = 0
Private Const WINNER_COLUMN as Integer = 1
Private Const CATEGORY_COLUMN as Integer = 2
Private Const YEAR_COLUMN as Integer = 3
Private Sub mnuUndoAutoCol_Click(ByVal sender as System.Object, ByVal e as System.EventArgs) _
    Handles rbCategory.Click, rbYear.Click, rbMovie.Click, rbWinner.Click, rbNoGroup.Click
    Select Case CType(sender, RadioButton).Text
        Case "by Category"
            lvOscars.AutoGroup(CATEGORY_COLUMN)
        Case "by Year"
            lvOscars.AutoGroup(YEAR_COLUMN)
        Case "by Movie"
            lvOscars.AutoGroup(MOVIENAME_COLUMN)
        Case "by Winner"
            lvOscars.AutoGroup(WINNER_COLUMN)
        Case "No Grouping"
            lvOscars.ShowGroups = False
    End Select
    CType(sender, RadioButton).Checked = True
End Sub

A tiling mode is also available in the XPListView control. The standard Microsoft implementation will not allow you to specify what subitems to display but with the XPCC control simply set the TileColumns property to an array of subitem indexes that you want to display. The text for those columns is rendered as specified for the subitem, so you can control how the list is drawn:

'set to tile mode
lvOscars.View = View.Tile
'use subitem(1) and subitem(2) for the second and third line in the tile view
lvOscars.TileColumns = New Integer() {1,2}
'alter the font for the first text line (the header)
lvOscars.SetColumnStyle(MOVIENAME_COLUMN, New Font(Me.lvOscars.Font, FontStyle.Bold), _
    Me.lvOscars.ForeColor, Me.lvOscars.BackColor)

Using the login controls

The XPLogin control mimics a single user entry in Windows XP’s login screen. You can set the icon (a 32 x 32-pixel image), the username and a helper string, and you can indicate wether or not the user needs password identification.
After entering the password or clicking the control, you will receive a Login event where you can check for the correct username/password.
To simplify things even more you can use the XPLoginList control to add multiple users to the list of XPLogins. This list supports events (Activated, Selected, Authenticate and Authenticated) that allow you to control the login process. For example, if your user must provide a password, the Authenticate event is raised so you can check the password’s validity.

Links

Link to .NET 2.0 Version: http://xpcc.codeplex.com
Link to .NET 4.6 Version: https://github.com/mdobler/xpCommon

(c) 2006, Michael Dobler

Site Map

Pages

Categories