Adding C1Themes to an existing WinForms application

April 25 2014

In this post I will show how to add C1Themes support to an existing WinForms application. The application I will be using is the C1dView sample shipped with C1Reports. It is a C1Report/C1PrintDocument viewer application with a C1Ribbon-based UI. As shipped, it does not include themes. The few simple steps described below add the ability for the end user to select and apply one of the predefined themes included in the C1Themes product, to the C1dView app. (Note: to follow those steps, you must have C1Reports, C1Command, C1Ribbon and C1Themes products - all part of the ComponentOne Studio for WinForms - installed on your system; I will be using C# but the same can easily be done in VB.)

Open the C1dView_2010.sln, and add a reference to C1.Win.C1Themes.4 to the project references (as mentioned above, you should have ComponentOne Studio for WinForms - which includes C1Themes - installed on your system):
I will be adding the theme selection combo to the "configuration toolbar" of the C1Ribbon on the main app's form. In order to do that, open the C1dView.cs (the main form of the application) in the Visual Studio form designer, click on the C1Ribbon, and in the Properties window expand the ConfigToolBar node of the rbnMain ribbon. There, open the Items collection editor - initially it contains just one item which is the app's Help menu:
Add a ComboBox item to the Items collection, change its name to rcmbTheme:
Close the collection editor, and in the Properties' selected component dropdown, select the newly added rcmbTheme item (C1.Win.C1Ribbon.RibbonComboBox). Switch to the events tab, and add two event handlers - for the DropDown and ChangeCommitted events of the combo. The rcmbTheme_DropDown handler will populate the combo with available theme names, while the rcmbTheme_ChangeCommitted will actually apply the selected theme to the form. Also, change the Label on the combo to "Theme:":
The code for the DropDown event handler added in the previous step should look like this:
```
using C1.Win.C1Themes;  
...  
private void rcmbTheme_DropDown(object sender, EventArgs e)  
{  
  rcmbTheme.Items.Clear();  
  string[] themes = C1ThemeController.GetThemes();  
  foreach (string theme in themes)  
    rcmbTheme.Items.Add(theme);  
}  
```
The first line clears the list to ensure that no stale info is there when the dropdown opens (alternatively you could cache the list of themes and reuse it). The next line is the one that fetches the names of all available themes. Because we have not added any custom themes to the project, the available themes here are just the standard ones built into the C1Themes assembly. We then add all themes to the combo so that the user can select a theme.
The code for the ChangeCommitted handler which actually applies the selected theme to the form is even shorter, here it is:
```
using C1.Win.C1Themes;  
...  
private void rcmbTheme_ChangeCommitted(object sender, EventArgs e)  
{  
  C1Theme theme = C1ThemeController.GetThemeByName(rcmbTheme.Text, false);  
  if (theme != null)  
    C1ThemeController.ApplyThemeToControlTree(this, theme);  
}  
```
The first call returns the C1Theme object with the name selected by the user. The 2nd argument (false) indicates that no exception should be thrown if the theme could not be found. We then apply the selected theme to the current form and all controls on it.
That's all there is to it really. Now when you run the app, there will be a combobox in the top right corner of the main form, filled with the list of standard themes shipped with C1Themes. Selecting a theme from that combo will change the appearance of the main form and all controls on it in accordance with the selected theme - here is a screenshot with the VS2013DarkSolar theme selected:

Some final notes:

The approach described here only allows to use the standard themes built into the C1Themes assembly. To use other themes (e.g. themes you may have created or modified using the C1ThemeDesigner application), certain additional steps must be taken. I will explain how to do that in another post.
I did not write any code to persist the theme selection between runs of the program - the end user will have to select the theme each time they run the app (which is not very user-friendly of course). It is an easy modification to save the selected theme's name in program settings, and apply it when the app starts. An even better alternative though is to use the C1.Win.C1Themes.C1ThemeLocator type instead of a simple theme name string - I will go into more detail in another post dedicated to it.
The C1dView app allows to create a new window - code needs to be added to apply the currently selected theme to that window too. Without that, new windows will have the default non-themed look.

Here is the modified C1dView sample (with theme name saved in settings, and theme applied to new windows). This is all for now. Comments and questions are welcome.

Adding C1Themes to an existing WinForms application

Read more about WinForms Edition >>