Shaping Gauge Elements

• Nov 16, 2018
• 3 minutes to read

Each gauge element comes with a set of embedded shapes that specify this element’s contour (form). Gauge elements change their shapes when you apply different gauge styles and presets, or modify the ShapeType property. If an element does not provide a shape that fits your requirements, you can create a custom shape for this element.

There are multiple gauge shapes included in the Gauges library, all derived from the base DevExpress.XtraGauges.Core.Drawing.BaseShape class as shown below.

All these shapes can be combined by their level of complexity into two groups.

• Compound shapes. Shapes with no form that serve as containers for simple shapes. From all gauge shapes, only the ComplexShape is compound.
• Simple shapes. These are simple shapes drawn according to a specific algorithm - arcs, ellipses, sectors, etc. Multiple simple shapes can be packed into a compound shape, the more simple shapes you combine - the more intricate and fancy your gauge elements will look. All BaseShape class descendants except for the ComlexShape are simple shapes.

Refer to this KB article for a description on each shape and an illustrated example of how to apply this or that shape to a gauge needle. Make a note that there are no special shapes for needles, shapes for background layers, shapes for spindle caps, etc.; you can apply them to any gauge element that exposes the Shape property.

Shaping any gauge element takes four steps.

1. Access the required element’s Shape property and cast it to the ComplexShape class. Even if your custom shape will be based on one simple shape, you have to place it within a compound shape first.

   C#

   
   ComplexShape needleShape = (ComplexShape)needle.Shape;
   

   VB.NET

   
   Dim needleShape As ComplexShape = CType(needle.Shape, ComplexShape)
   

2. Clear your compound shape by calling the .Collection.Clear() method.

   C#

   
   needleShape.Collection.Clear();
   

   VB.NET

   
   needleShape.Collection.Clear()
   

3. Create one or multiple simple shapes from which your ComplexShape will consist of.

   C#

   
   PolylineShape basic = new PolylineShape(new PointF[] {
       new PointF(25, 20), new PointF(100, 0), new PointF(25, -20),
       new PointF(95, 0), new PointF(25, 20)
   });
   basic.Appearance.ContentBrush = new SolidBrushObject(Color.Azure);
   basic.Name = "basic";
   
   PolylineShape cap = new PolylineShape(new PointF[] {
       new PointF(100, 0), new PointF(105, 5), 
       new PointF(110, 0), new PointF(105, -5)
   });
   cap.Appearance.ContentBrush = new SolidBrushObject(Color.BurlyWood);
   cap.Name = "cap";
   

   VB.NET

   
   Dim basic As New PolylineShape(New PointF() {
       New PointF(25, 20),
       New PointF(100, 0),
       New PointF(25, -20),
       New PointF(95, 0),
       New PointF(25, 20)
   })
   basic.Appearance.ContentBrush = New SolidBrushObject(Color.Azure)
   basic.Name = "basic"
   
   Dim cap As New PolylineShape(New PointF() {
       New PointF(100, 0),
       New PointF(105, 5),
       New PointF(110, 0),
       New PointF(105, -5)
   })
   cap.Appearance.ContentBrush = New SolidBrushObject(Color.BurlyWood)
   cap.Name = "cap"
   

4. Now add all simple shapes to the ComplexShape object.

   C#

   
   needleShape.AddRange(new BaseShape[] { basic, cap });
   

   VB.NET

   
   needleShape.AddRange(New BaseShape() { basic, cap })
   

   Your gauge element (a needle in this example) will now take a unique form based on these custom shapes you have created. The following figure illustrates a result.

   

Important

Modifying the ShapeType property for a gauge element will break all shape customizations made to this element and apply one of the standard embedded shapes.