Lesson 1 - Create a Circular Gauge

  • 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.

This tutorial consists of the following steps.

  1. Create a New Project and Add a Gauge Control
  2. Add a Scale
  3. Add Value Indicators
  4. Specify Ranges
  5. Result

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 MS Visual Studio 2012, 2013, 2015, 2017 or 2019.
  • 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.20.1: Data & Analytics tab and drop it onto the main window.

    Lesson1_01_Toolbox

  • 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.

    Lesson1_015_ResetLayout

  • After this, your XAML may look like the following. If it doesn't, you can overwrite your code with:

    <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" />
        </Grid>
    </Window>
    

    Note that you can add CircularGaugeControl by overwriting your MainWindow.xaml file with this code without dragging the CircularGaugeControl control to the window. However, in this case, you need to manually add references to the following libraries:

    DevExpress.Data.v20.1, DevExpress.Xpf.Core.v20.1, DevExpress.Xpf.Gauges.v20.1.

    DXScheduler_AddReference

    NOTE

    Normally, when adding references to these assemblies, you should choose them from the Global Assembly Cache (GAC). However, if you prefer to copy them locally, or need to include them later into your product's installation, you can find their copies in the following directory.

    C:\Program Files (x86)\DevExpress 20.1\Components\Bin\Framework\

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.

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).

    To do this, locate the ArcScale.Needles property of the arc scale added in the previous step, invoke the Needles collection editor and click Add. After that set the ValueIndicatorBase.Value property of the newly created ArcScaleNeedle object to 3.

    Lesson1_04_NeedleProperties

    Let's add one more needle to our clock to show minutes and set its ValueIndicatorBase.Value property to 12.

    Lesson1_045_Needle2Properties

    NOTE

    A Circular gauge can contain multiple needles, and each needle is displayed using presentation settings defined by the current CircularGaugeControl.Model. This means that if a model contains different presentations for its needles, then the second needle may look, for example, like a minute hand, and the third needle may look like a second hand.

    If you want to customize the appearance of a particular needle, use its ArcScaleNeedle.Presentation property.

  • Add a Marker that will indicate any "fixed" value on a scale (e.g. an alarm that should ring at 7:00).

    To do this, locate the ArcScale.Markers property, invoke the Markers collection editor and click Add. After that set the ValueIndicatorBase.Value property of the newly created ArcScaleMarker object to 7.

    Lesson1_05_MarkerProperties

  • Now add a Range Bar that will indicate the difference between any "anchored" value and the current value.

    To do this, locate the ArcScale.RangeBars property, invoke the RangeBars collection editor and click Add. After that set the ArcScaleRangeBar.AnchorValue property of the newly created ArcScaleRangeBar object to 7 and ValueIndicatorBase.Value to 3.

    Lesson1_06_RangeBarProperties

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.

<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>

Run the application and see the result.

Lesson1_07_Result

TIP

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E3199.

See Also