How To: Create a Gauge From Scratch (Runtime)

  • 9 minutes to read

This example illustrates how to create the same gauge as in the Creating a Gauge from Scratch walkthrough, but entirely in code. Unlike other 'How to' examples that make use of the AddDefaultElement method called for a required gauge (e.g., the CircularGauge.AddDefaultElements method), the following code does not create any predefined elements. Instead, all elements are created and customized manually.

There are two ways of adding gauge elements manually. The most convenient way is to use the desired Add... methods from code (e.g., CircularGauge.AddNeedle, LinearGauge.AddScale, DigitalGauge.AddBackgroundLayer, etc.). Not only do these methods add related gauge elements to the gauge, but they also automatically customize these elements according to the most frequently used scenarios. For instance, calling the AddScale method will result in adding a scale, whose tickmarks are already formatted to display integer values. Thus, you won't need to call set the MajorTickmark.FormatString property manually.

The alternate approach is to instantiate objects of desired classes (ArcScaleComponent, LinearScaleMarkerComponent, DigitalBackgroundLayerComponent, etc.), then manually specify their settings and add to the related collections of your gauge (e.g., the CircularGauge.Needles collection that holds all needles owned by this gauge). When following this approach, make sure to set all significant properties manually. For instance, you will need to specify names for all your manually created elements.

Whichever approach you choose, wrap any code that customizes gauge elements in the BeginUpdate*EndUpdate* method pair. By doing so, you avoid excessive element visual updates.


using System.Drawing;
using System.Windows.Forms;
using DevExpress.XtraGauges.Core.Model;
using DevExpress.XtraGauges.Win.Base;
using DevExpress.XtraGauges.Win.Gauges.Circular;

namespace GaugeFromSratch {
    public partial class Form1 : Form {
        public Form1() {
            InitializeComponent();
            gaugeControl1.Gauges.Add(CreateCircularGauge());
        }

        CircularGauge CreateCircularGauge() {
            CircularGauge gauge = new CircularGauge();
            gauge.BeginUpdate();
            var scales = CreateScales(gauge);
            var smallScale = scales[0];
            var largeScale = scales[2];
            CreateValueIndicators(gauge, smallScale, largeScale);
            CreateScaleRanges(gauge, smallScale, largeScale);
            CreateOrnamentalElements(gauge, largeScale);
            //Two trackbars are placed onto the form to test whether or not value indicators are bound to related scales correctly
            trackBar1.ValueChanged += (s, e) => smallScale.Value = trackBar1.Value;
            trackBar2.ValueChanged += (s, e) => largeScale.Value = trackBar2.Value;
            gauge.EndUpdate();
            return gauge;
        }

        ArcScaleComponent[] CreateScales(CircularGauge gauge) {
            // smallScale 
            var smallScale = new ArcScaleComponent();
            smallScale.BeginUpdate();
            smallScale.Name = "smallScale";
            smallScale.StartAngle = -240f;
            smallScale.EndAngle = 60f;
            smallScale.Center = new DevExpress.XtraGauges.Core.Base.PointF2D(125, 125);
            smallScale.RadiusX = 30F;
            smallScale.RadiusY = 30F;
            smallScale.MaxValue = 40F;
            smallScale.MinValue = -40F;
            smallScale.Value = trackBar1.Value;
            smallScale.MajorTickCount = 9;
            smallScale.MajorTickmark.FormatString = "{0:F0}";
            smallScale.MajorTickmark.ShapeScale = new DevExpress.XtraGauges.Core.Base.FactorF2D(0.7F, 0.9F);
            smallScale.MajorTickmark.ShapeType = DevExpress.XtraGauges.Core.Model.TickmarkShapeType.Circular_Style10_4;
            smallScale.MajorTickmark.TextOffset = 15F;
            smallScale.MajorTickmark.TextOrientation = DevExpress.XtraGauges.Core.Model.LabelOrientation.LeftToRight;
            smallScale.AppearanceTickmarkText.Font = new System.Drawing.Font("Tahoma", 8F);
            smallScale.AppearanceTickmarkText.TextBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.Gray);
            smallScale.MinorTickCount = 4;
            smallScale.MinorTickmark.ShapeScale = new DevExpress.XtraGauges.Core.Base.FactorF2D(0.7F, 0.4F);
            smallScale.MinorTickmark.ShapeType = DevExpress.XtraGauges.Core.Model.TickmarkShapeType.Circular_Style10_2;
            smallScale.EndUpdate();
            // mediumScale 
            var mediumScale = new ArcScaleComponent();
            mediumScale.BeginUpdate();
            mediumScale.Name = "mediumScale";
            mediumScale.StartAngle = -240f;
            mediumScale.EndAngle = 60f;
            mediumScale.Center = new DevExpress.XtraGauges.Core.Base.PointF2D(125, 125);
            mediumScale.RadiusX = 80F;
            mediumScale.RadiusY = 80F;
            mediumScale.MinValue = 720F;
            mediumScale.MaxValue = 780F;
            mediumScale.MajorTickCount = 7;
            mediumScale.MajorTickmark.FormatString = "{0:F0}";
            mediumScale.MajorTickmark.ShapeScale = new DevExpress.XtraGauges.Core.Base.FactorF2D(0.7F, 1F);
            mediumScale.MajorTickmark.ShapeType = DevExpress.XtraGauges.Core.Model.TickmarkShapeType.Circular_Style10_4;
            mediumScale.MajorTickmark.TextOffset = 15F;
            mediumScale.MajorTickmark.TextOrientation = DevExpress.XtraGauges.Core.Model.LabelOrientation.Tangent;
            mediumScale.AppearanceTickmarkText.Font = new System.Drawing.Font("Tahoma", 8F);
            mediumScale.AppearanceTickmarkText.TextBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.Gray);
            mediumScale.MinorTickCount = 4;
            mediumScale.MinorTickmark.ShapeScale = new DevExpress.XtraGauges.Core.Base.FactorF2D(1.1F, 0.5F);
            mediumScale.MinorTickmark.ShapeType = DevExpress.XtraGauges.Core.Model.TickmarkShapeType.Circular_Style10_2;
            mediumScale.EndUpdate();
            // largeScale 
            var largeScale = new ArcScaleComponent();
            largeScale.BeginUpdate();
            largeScale.Name = "largeScale";
            largeScale.Center = new DevExpress.XtraGauges.Core.Base.PointF2D(125, 125);
            largeScale.RadiusX = 110F;
            largeScale.StartAngle = -240f;
            largeScale.EndAngle = 60f;
            largeScale.RadiusY = 110F;
            largeScale.MinValue = 960F;
            largeScale.MaxValue = 1040F;
            largeScale.Value = trackBar2.Value;
            largeScale.MajorTickCount = 9;
            largeScale.MajorTickmark.FormatString = "{0:F0}";
            largeScale.MajorTickmark.ShapeScale = new DevExpress.XtraGauges.Core.Base.FactorF2D(0.7F, 1F);
            largeScale.MajorTickmark.ShapeType = DevExpress.XtraGauges.Core.Model.TickmarkShapeType.Circular_Style10_4;
            largeScale.MajorTickmark.TextOffset = 15F;
            largeScale.MajorTickmark.TextOrientation = DevExpress.XtraGauges.Core.Model.LabelOrientation.Tangent;
            largeScale.AppearanceTickmarkText.Font = new System.Drawing.Font("Tahoma", 8F);
            largeScale.AppearanceTickmarkText.TextBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.Gray);
            largeScale.MinorTickCount = 4;
            largeScale.MinorTickmark.ShapeScale = new DevExpress.XtraGauges.Core.Base.FactorF2D(1.1F, 0.5F);
            largeScale.MinorTickmark.ShapeType = DevExpress.XtraGauges.Core.Model.TickmarkShapeType.Circular_Style10_2;
            largeScale.EndUpdate();
            var scales = new ArcScaleComponent[] { smallScale, mediumScale, largeScale };
            gauge.Scales.AddRange(scales);
            return scales;
        }

        void CreateValueIndicators(CircularGauge gauge, ArcScaleComponent smallScale, ArcScaleComponent largeScale) {
            // A value indicator related to the inner scale
            var needle = new ArcScaleNeedleComponent();
            needle.BeginUpdate();
            needle.Name = "needle";
            needle.ArcScale = smallScale;
            needle.StartOffset = 18F;
            needle.EndOffset = 5F;
            needle.ShapeType = DevExpress.XtraGauges.Core.Model.NeedleShapeType.CircularHalf_Style23;
            needle.ZOrder = -50;
            needle.EndUpdate();
            // A value indicator related to the outer scale
            var marker = new ArcScaleMarkerComponent();
            marker.BeginUpdate();
            marker.Name = "marker";
            marker.ArcScale = largeScale;
            marker.ShapeOffset = 27F;
            marker.Shader = new DevExpress.XtraGauges.Core.Drawing.StyleShader() { StyleColor1 = Color.SlateBlue, StyleColor2 = Color.CornflowerBlue };
            marker.ShapeScale = new DevExpress.XtraGauges.Core.Base.FactorF2D(0.8F, 1F);
            marker.ZOrder = -100;
            marker.EndUpdate();

            gauge.Needles.Add(needle);
            gauge.Markers.Add(marker);
        }

        void CreateScaleRanges(CircularGauge gauge, ArcScaleComponent smallScale, ArcScaleComponent largeScale) {
            //Outer green range
            ArcScaleRange outerGreenRange = new ArcScaleRange();
            outerGreenRange.AppearanceRange.ContentBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.SeaGreen);
            outerGreenRange.StartThickness = 4F;
            outerGreenRange.EndThickness = 4F;
            outerGreenRange.StartValue = 970F;
            outerGreenRange.EndValue = 991F;
            outerGreenRange.ShapeOffset = 33F;
            //Outer yellow range
            ArcScaleRange outerYellowRange = new ArcScaleRange();
            outerYellowRange.AppearanceRange.ContentBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.Khaki);
            outerYellowRange.StartThickness = 4F;
            outerYellowRange.EndThickness = 4F;
            outerYellowRange.StartValue = 991F;
            outerYellowRange.EndValue = 1009F;
            outerYellowRange.ShapeOffset = 33F;
            //Outer red range
            ArcScaleRange outerRedRange = new ArcScaleRange();
            outerRedRange.AppearanceRange.ContentBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.LightCoral);
            outerRedRange.StartValue = 1009F;
            outerRedRange.EndValue = 1030F;
            outerRedRange.StartThickness = 4F;
            outerRedRange.EndThickness = 4F;
            outerRedRange.ShapeOffset = 33F;
            //Inner blue range
            ArcScaleRange innerBlueRange = new ArcScaleRange();
            innerBlueRange.AppearanceRange.ContentBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.CornflowerBlue);
            innerBlueRange.StartValue = -40F;
            innerBlueRange.EndValue = 0F;
            innerBlueRange.StartThickness = 4F;
            innerBlueRange.EndThickness = 4F;
            innerBlueRange.ShapeOffset = 0F;
            //Inner yellow range
            ArcScaleRange innerYellowRange = new ArcScaleRange();
            innerYellowRange.AppearanceRange.ContentBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.Khaki);
            innerYellowRange.StartValue = 0F;
            innerYellowRange.EndValue = 40F;
            innerYellowRange.StartThickness = 4F;
            innerYellowRange.EndThickness = 4F;
            innerYellowRange.ShapeOffset = 0F;
            //Adding ranges to scales
            smallScale.Ranges.AddRange(new ArcScaleRange[] { innerBlueRange, innerYellowRange });
            largeScale.Ranges.AddRange(new ArcScaleRange[] { outerGreenRange, outerYellowRange, outerRedRange });
        }

        void CreateOrnamentalElements(CircularGauge gauge, ArcScaleComponent largeScale) {
            ArcScaleBackgroundLayerComponent backgroundLayer = new ArcScaleBackgroundLayerComponent();
            backgroundLayer.BeginUpdate();
            backgroundLayer.Name = "backgroundLayer";
            backgroundLayer.ShapeType = DevExpress.XtraGauges.Core.Model.BackgroundLayerShapeType.CircularFull_Style23;
            backgroundLayer.ArcScale = largeScale;
            backgroundLayer.Size = new SizeF(350F, 350F);
            backgroundLayer.ZOrder = 1000;
            backgroundLayer.EndUpdate();
            //Custom label 1
            LabelComponent mmLabel = new LabelComponent();
            mmLabel.BeginUpdate();
            mmLabel.Name = "mmLabel";
            mmLabel.Text = "mm";
            mmLabel.Position = new DevExpress.XtraGauges.Core.Base.PointF2D(128, 210);
            mmLabel.AppearanceText.TextBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.Gray);
            mmLabel.EndUpdate();
            //Custom label 2
            LabelComponent mbLabel = new LabelComponent();
            mbLabel.BeginUpdate();
            mbLabel.Name = "mbLabel";
            mbLabel.Text = "millibars";
            mbLabel.Position = new DevExpress.XtraGauges.Core.Base.PointF2D(128, 238);
            mbLabel.AppearanceText.TextBrush = new DevExpress.XtraGauges.Core.Drawing.SolidBrushObject(Color.Gray);
            mbLabel.EndUpdate();
            //Adding backgrounds and labels to the gauge
            gauge.BackgroundLayers.Add(backgroundLayer);
            gauge.Labels.AddRange(new LabelComponent[] { mmLabel, mbLabel });
        }
    }
}