How to: Move Value Indicators at Runtime

Oct 29, 2020
7 minutes to read

This example illustrates how to grant your end-users the capability to move a gauge needle by dragging it or clicking a gauge scale. Note that you can do this on any type of value indicator, not only needles.

Handle the MouseDown and MouseMove events, inherited from the System.Windows.Forms.Control class.
Use the CalcHitInfo method provided by the IGaugeContainer interface. This method takes a point as a parameter and returns the gauge hit information. You can use this information to get which gauge element is located at the target coordinates.
A rendered gauge is always surrounded by a gauge background (see the figure below).
Convert the click coordinates to gauge coordinates by using the PointToModelPoint method of the DevExpress.XtraGauges.Core.Primitive.MathHelper class.
Now, convert gauge coordinates to a scale value. First, use the ArcScale.PointToPercent method (the LinearScale.PointToPercent method for linear gauges). This method will return the percentage of the ‘filled’ scale compared to this entire scale. Then, call the ArcScale.PercentToValue/LinearScale.PercentToValue method to convert this relative value to an absolute scale value. Finally, apply this value to a scale (or to a value indicator if it is not bound to scale values).
For the MouseMove event, you need to do exactly the same as before, except for one additional condition: check the Button parameter of the received MouseEventArgs data to get whether or not an end-user moves the mouse pointer while holding left mouse button down.
Move your code from event handlers to a separate method to avoid code duplication.
Use the following code to change the mouse pointer when it hovers a rendered gauge. This small enhancement will give your customers a tip that the gauge is clickable.
Launch the application to see the result.

Complete Code

This section lists the complete example code. Also, the DevExpress Demo Center contains a demo module for this example (‘Gauge and Indicators’ demo, ‘Event-based Interaction’ module). Click the ‘Open Solution’ button to open this demo module in Visual Studio.

C#
VB.NET

csharp

using System.Drawing;
using System.Windows.Forms;
using DevExpress.XtraGauges.Base;
using DevExpress.XtraGauges.Core.Base;
using DevExpress.XtraGauges.Core.Model;
using DevExpress.XtraGauges.Core.Primitive;

namespace DevExpress.XtraGauges.Demos {
    public partial class ClickableGauge {
        public InteractionFeature() {
            InitializeComponent();
        }
        void gaugeControl1_MouseMove(object sender, MouseEventArgs e) {
            CheckCursor(gaugeControl1 as IGaugeContainer, e);
            if(e.Button == MouseButtons.Left)
                CalculateMouseValue(gaugeControl1 as IGaugeContainer, arcScaleComponent1, e);
        }
        void gaugeControl1_MouseDown(object sender, MouseEventArgs e) {
            CalculateMouseValue(gaugeControl1 as IGaugeContainer, arcScaleComponent1, e);
        }
        void CalculateMouseValue(IGaugeContainer container, IConvertibleScaleEx scale, MouseEventArgs e) {
            BasePrimitiveHitInfo hi = container.CalcHitInfo(e.Location);
            if(hi.Element != null && !hi.Element.IsComposite) {
                PointF modelPt = MathHelper.PointToModelPoint(scale as IElement<IRenderableElement>, new PointF(e.X, e.Y));
                float percent = scale.PointToPercent(modelPt);
                scale.Value = scale.PercentToValue(percent);
            }
        }
        void CheckCursor(IGaugeContainer container, MouseEventArgs e) {
            BasePrimitiveHitInfo hi = container.CalcHitInfo(e.Location);
            Cursor cursor = (hi.Element != null && !hi.Element.IsComposite) ? 
                Cursors.Hand : Cursors.Default;
            if(((Control)container).Cursor != cursor) 
                ((Control)container).Cursor = cursor;
        }
    }
}

Imports System.Drawing
Imports System.Windows.Forms
Imports DevExpress.XtraGauges.Base
Imports DevExpress.XtraGauges.Core.Base
Imports DevExpress.XtraGauges.Core.Model
Imports DevExpress.XtraGauges.Core.Primitive

Namespace DevExpress.XtraGauges.Demos
    Partial Public Class ClickableGauge
        Private Function InteractionFeature() As Public
            InitializeComponent()
        End Function
        Private Sub gaugeControl1_MouseMove(ByVal sender As Object, ByVal e As MouseEventArgs)
            CheckCursor(TryCast(gaugeControl1, IGaugeContainer), e)
            If e.Button = MouseButtons.Left Then
                CalculateMouseValue(TryCast(gaugeControl1, IGaugeContainer), arcScaleComponent1, e)
            End If
        End Sub
        Private Sub gaugeControl1_MouseDown(ByVal sender As Object, ByVal e As MouseEventArgs)
            CalculateMouseValue(TryCast(gaugeControl1, IGaugeContainer), arcScaleComponent1, e)
        End Sub
        Private Sub CalculateMouseValue(ByVal container As IGaugeContainer, ByVal scale As IConvertibleScaleEx, ByVal e As MouseEventArgs)
            Dim hi As BasePrimitiveHitInfo = container.CalcHitInfo(e.Location)
            If hi.Element IsNot Nothing AndAlso (Not hi.Element.IsComposite) Then
                Dim modelPt As PointF = MathHelper.PointToModelPoint(TryCast(scale, IElement(Of IRenderableElement)), New PointF(e.X, e.Y))
                Dim percent As Single = scale.PointToPercent(modelPt)
                scale.Value = scale.PercentToValue(percent)
            End If
        End Sub
        Private Sub CheckCursor(ByVal container As IGaugeContainer, ByVal e As MouseEventArgs)
            Dim hi As BasePrimitiveHitInfo = container.CalcHitInfo(e.Location)
            Dim cursor As Cursor = If(hi.Element IsNot Nothing AndAlso (Not hi.Element.IsComposite), Cursors.Hand, Cursors.Default)
            If DirectCast(container, Control).Cursor IsNot cursor Then
                DirectCast(container, Control).Cursor = cursor
            End If
        End Sub
    End Class
End Namespace