Global Renderers

Most of the WinForms control products have the concept of global renderers. Global renderers allow you to easily use the same single instance of a control renderer for all control instances that use that renderer type. This provides an easy way to provide a consistent theme across an application and also saves on resources since all controls of the same type reuse a single renderer as opposed to each control having its own renderer instance.

The Renderer Manager

All global renderers are managed by the UIRendererManager class that is located in the ActiproSoftware.UI.WinForms.Controls namespace, within the ActiproSoftware.Shared.WinForms assembly. It has a number of static methods that provide control over all of the renderers currently being managed.

Changing the Global Color Scheme

The UIRendererManager tracks a global color scheme, which is the color scheme that the global renderers should use. The color scheme is of type WindowsColorScheme, which is located in the ActiproSoftware.UI.WinForms.Drawing namespace, within the ActiproSoftware.Shared assembly. There are a number of built-in color schemes (available from static properties off of WindowsColorScheme), or you can inherit the WindowsColorScheme class and build your own custom color scheme.

Once you have determined which color scheme you'd like to use, set it to the static UIRendererManager.ColorScheme property, and all the global renderers will attempt update to use that color scheme.

This code demonstrates how to set the color scheme to a built-in Metro Light theme:

UIRendererManager.ColorScheme = WindowsColorScheme.MetroLight;

Using the UIRendererManager Component

Although all the renderer managing functionality is on the static instance of a UIRendererManager, The UIRendererManager is also a Component. This means it can be dropped on a Form in the designer. The benefit of this is that when the UIRendererManager.ColorSchemeType instance property is set, it auto-updates the UIRendererManager.ColorScheme static property to be the related color scheme.

This means that you can drop an instance of UIRendererManager on your application's main Form, set the color scheme type that you'd like to use, and once the main Form is loaded at run-time, it and all the other child windows after it will use that color scheme.

Setting a Custom Global Renderer Factory

There may be certain cases where you'd like to use a global renderer that is different than the default. For instance, say you'd like to use the VisualStudioToolWindowTabStripRenderer by default for all standalone TabStrip controls in your application. You can create a class which implements IUIRendererFactory.

The IUIRendererFactory.CreateRenderer method implemented on the custom factory class is responsible for returning an instance if IUIRenderer, which is the interface that all renderers implement.

This code demonstrates how to implement a renderer factory for our Visual Studio TabStrip renderer:

public class CustomTabStripRendererFactory : IUIRendererFactory {
	IUIRenderer IUIRendererFactory.CreateRenderer() {
		return new VisualStudioToolWindowTabStripRenderer();
	}
}

Now that the factory class is available, it must be assigned to the UIRendererManager. This is done by a call to the static UIRendererManager.RegisterRendererFactory method. The renderer type must be specified, which is the renderer-specific interface type to be served by the factory class. In our example, it would be the ITabStripRenderer interface. We must also indicate to overwrite any existing renderer factory for the renderer type.

This code demonstrates how to set the custom renderer factory:

UIRendererManager.RegisterRendererFactory(typeof(ITabStripRenderer),
	new CustomTabStripRendererFactory(), overwrite: true);

At this point any standalone TabStrip control that doesn't have a control-specific renderer assigned to it will use the global VisualStudioToolWindowTabStripRenderer instance created by the factory.

Renderer vs. RendererResolved Properties

Each control that supports custom rendering has a Renderer (or similarly-named) property and a corresponding RendererResolved property. The Renderer property will be null by default and should be used to get or set the control-specific renderer to use. If it is set, the appropriate global renderer will not be used. The RendererResolved property is a read-only property and either returns the control-specific renderer (if set), or the global renderer that is in use by the control.