Lesson 1 - Create a Circular Gauge

Dec 18, 2023
6 minutes to read

This is the first tutorial of the DXGauges Getting Started series. It will guide you through the process of creating a Circular gauge and adjusting its common settings.

View Example: Create a Circular Gauge

Step 1. Create a New Project and Add a Gauge Control

In this step we will perform the common actions that are required when you add a Gauge control to your application.

Run Microsoft Visual Studio.
Create a new WPF Application project.
Now add the CircularGaugeControl component to your project. To do this, locate the CircularGaugeControl item in a Visual Studio toolbox on the DX.25.2: Data & Analytics tab and drop it onto the main window.
Right-click the CircularGaugeControl object and choose the Reset Layout | All option in the context menu. This will stretch the Gauge control to fill the whole window.
After this, your XAML may look like the following. If it doesn’t, you can overwrite your code with:

Now we have a Gauge control added to our application and can customize it to meet our requirements.

Step 2. Add a Scale

Scales are the main elements of a Gauge control because they contain all other visual elements. The Gauge control can consist of multiple scales, each with an independent set of elements and options, and all scales are stored in the CircularGaugeControl.Scales collection.

In this lesson we need to add only one scale for demonstration purposes.

To add a scale, locate the CircularGaugeControl.Scales property in a Properties window and click the ellipsis button to invoke the Scales collection editor. In this editor, add a new ArcScale object using the Add button.
For the newly created scale, set its properties as follows.
Now the Gauge control should look as shown in the image below.

Step 3. Add Value Indicators

In this step, we will add basic elements that visually represent current values on a Circular scale. In most cases, Circular scales support three indicator types: Needles, Markers and Range Bars.

Add a Needle element that will indicate the current measurement value (e.g. the current time in hours).
Add a Marker that will indicate any “fixed” value on a scale (e.g. an alarm that should ring at 7:00 ).
Now add a Range Bar that will indicate the difference between any “anchored” value and the current value.

Step 4. Specify Ranges

Ranges are intended to visually identify different intervals on a scale. For example, this can be working or non-working hours, day or night, or something else. On our scale, we will show several equal ranges for demonstration purposes.

To do this, locate the ArcScale.Ranges property, invoke the Ranges collection editor and add 3 ranges.

Note that for each range you can set RangeBase.StartValue and RangeBase.EndValue property values in either absolute values or in percents. In our example, let’s set these properties as follows.

Range 1 : StartValue - 0, EndValue - 4.
Range 2 : StartValue - 4, EndValue - 8.
Range 3 : StartValue - 8, EndValue - 12.

Step 5. Result

Now our Gauge control is ready.

XAML

xaml

<Window x:Class="DXGauges_Circular.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:dxga="http://schemas.devexpress.com/winfx/2008/xaml/gauges"
        Title="MainWindow" Height="350" Width="525" >
    <Grid>
        <dxga:CircularGaugeControl Name="circularGaugeControl1" >
            <dxga:CircularGaugeControl.Model>
                <dxga:CircularRedClockModel />
            </dxga:CircularGaugeControl.Model>
            <dxga:CircularGaugeControl.Scales>
                <dxga:ArcScale StartValue="0" EndValue="12" 
                               StartAngle="-90" EndAngle="270"
                               MajorIntervalCount="12" MinorIntervalCount="5" >
                    <dxga:ArcScale.LabelOptions>
                        <dxga:ArcScaleLabelOptions ShowFirst="False" />
                    </dxga:ArcScale.LabelOptions>
                    <dxga:ArcScale.Needles>
                        <dxga:ArcScaleNeedle Value="3" />
                        <dxga:ArcScaleNeedle Value="12" />
                    </dxga:ArcScale.Needles>
                    <dxga:ArcScale.Markers>
                        <dxga:ArcScaleMarker Value="7" />
                    </dxga:ArcScale.Markers>
                    <dxga:ArcScale.RangeBars>
                        <dxga:ArcScaleRangeBar AnchorValue="7" Value="3" />
                    </dxga:ArcScale.RangeBars>
                    <dxga:ArcScale.Layers>
                        <dxga:ArcScaleLayer />
                    </dxga:ArcScale.Layers>
                    <dxga:ArcScale.Ranges>
                        <dxga:ArcScaleRange StartValue="0" EndValue="4"/>
                        <dxga:ArcScaleRange StartValue="4" EndValue="8" />
                        <dxga:ArcScaleRange StartValue="8" EndValue="12" />
                    </dxga:ArcScale.Ranges>
                </dxga:ArcScale>
            </dxga:CircularGaugeControl.Scales>
        </dxga:CircularGaugeControl>
    </Grid>
</Window>