UserControl Tutorial

No modern presentation framework would be complete without the ability to create your own reusable controls. If no existing control has a programmatic interface that naturally represents your concept, go ahead and create a user control or custom control.

UserControls can be seen as a composition of existing controls. They contain a logical tree defining its look and tend to have logic that directly interacts with these child elements.

In contrast CustomControls are needed when you want to create a totally new control or extend the functionality of an existing control. A custom control tends to get its look from a visual tree defined in a separate control template and generally has logic that works even if the user changes its visual tree completely.

In this tutorial we will focus on the development of a simple user control that implements the typical numeric spinner. The next tutorial will be dedicated to custom controls.

Interface Creation

Let's create a very simple user control, a NumericUpDown control composed of two RepeatButtons to increment and decrement the value and a TextBlock to display it.

We are following the steps in the tutorial that describes how to extend NoesisGUI. The unique new detail here, apart from deriving from UserControl, is the GUI::LoadComponent call that indicates the XAML file that will be loaded when this user control is created.

Properties

Now we define the properties that this control will expose. We talked about the numeric spinner value, so this could be our first property: Value. A dependency property must be declared as a public static member with getter and setter accessors to facilitate the use of the control within the code:

The interface has a text block to show the spinner value. If we want to automatically update the interface we can bind its Text property to the Value property we just created. Besides that, the interface has two buttons that increment or decrement the value of the spinner, so we can add some code-behind that responds to the Click event of these buttons to update the Value property appropriately:

To connect events with code-behind functions we override ConnectEvent virtual function. This function is called for each event referenced in the associated xaml, and provides the event source along with the name of function that is expected to be called.

Events

Next step is exposing an event to notify users when the value of the numeric spinner changes. We call this event ValueChanged and implement it as a routed event. Routed events must be declared with a public static member and with a virtual function that raises the event so inheritors can override the basic implementation:

Improvements

The source code that accompanies this tutorial incorporates several improvements. We have extended the functionality of the spinner by adding new dependency properties to control the maximum and minimum value, and the step factor whenever the up/down buttons are clicked. It is recommended that you read the code carefully.

Usage

Now we can use our control in any other XAML file. For example as an editor for the values of an RGB color: