Version

Configuring the Needle (XamLinearGauge)

Purpose

This topic explains, with code examples, how to configure the needle of the XamLinearGauge™ control. This includes the value indicated by the needle, its width, position, and formatting.

Required background

The following topics are prerequisites to understanding this topic:

Topic Purpose

This topic provides conceptual information about the XamLinearGauge control including its main features, minimum requirements, and user functionality.

This topic explains how to add the XamLinearGauge control to a Xamarin.Forms application.

Configuring the Needle – Conceptual Overview

Needle configuration summary

Configuring the needle includes specifying the needle’s shape and size and its position across and along the scale. Further customizations can include configuring the look-and-feel of the needle (in terms of border thickness and color and fill color) .The shape of the needle is specified by setting the NeedleShape property to one of the pre-defined needle shape types or to the custom needle type. The pre-defined needle shapes are

  • Needle

  • Rectangle

  • Trapezoid

  • Triangle

The default needle shape is Needle which defines a rectangular needle body with a triangular point, like this:

XamLinearGauge Configuring the Needle 1.png

The custom needle shape type is specified by setting the NeedleShape property to “Custom” .

The pre-defined shapes are customizable. If you use any of the pre-defined needle shapes without customizing the shape, you are configuring a basic needle. Selecting either a custom shape or further customizing a pre-defined shape through its extent-type or width-based properties is considered configuring a custom needle.

Along the scale, the needle is always positioned at the value specified by the Value property.

The needle’s position in the across-the-scale dimension is configurable relative to the edges of the Graph area through the NeedleInnerExtent and NeedleOuterExtent properties. The needle shape is configured through the NeedleShape property. There are multiple predefined shapes that can be used for the needle. Custom shapes are also supported.

XamLinearGauge Overview 10.png

The look-and-feel of the needle can be customized in terms of fill color, border color, and border thickness using the respective properties ( NeedleBrush, NeedleOutline, and NeedleStrokeThickness).

Needle configuration summary chart

The following table explains briefly the configurable aspects of XamLinearGauge control’s needle and maps them to properties that manage them.

Configurable aspects Details Property Default value

Shape type

A value indicating the needle shape

Needle

Name

A name for the needle

Not set

Value to indicate

The value indicated by the needle

Not set

Size and position across the scale

The position of the inner edge of the needle

Defined in the default theme

The position of the outer edge of the needle

Defined in the default theme

Fill color of the bar

Defined in the default theme

Thickness of the needle’s border

Set in pixels

1.0

Color of the needle’s border

Defined in the default theme

Property settings

The following table maps the desired behavior to its respective property settings.

In order to configure: Use this property: And set it to:

Shape type

One of the predefined shapes or “Custom”

Name

A string expressing the name of the needle

Value to indicate

The desired value in the measures of the scale

Size and position across the scale

Across-the-scale position of the inner edge of the needle defined as a relative part of the height/width of the Graph area (depending on the orientation) presented as a fraction of 1 (e.g. 0.2).

Across-the-scale position of the outer edge of the needle defined as a relative part of the height/width of the Graph area(depending on the orientation) presented as a fraction of 1 (e.g. 0.2).

Fill color

The desired color

Border thickness

The desired value in pixels

Border color

The desired color

Configuring the Needle Shape

Needle shape configuration summary

Configuring the needle shape can be done for either the existing pre-defined shapes or to a custom shape. In the latter case, you can create an entirely new needle shape.

The needle shape is configured by setting the properties controlling the various widths and extents. These properties define the three basic parts which form the desired needle shape. The basic parts are (from top to bottom at vertical orientation):

  • Outer part – the part of the needle that is farthest from the scale

  • Middle part – the part between the Outer segment and the Inner segment. It shares its width-related properties with the other two segments.

  • Inner part – the part of the needle that is closest the scale

The following picture illustrates the properties related to the needle shape when horizontal orientation is used. For explanations of the properties, refer to Property reference.

XamLinearGauge Configuring the Needle 2.png

Property categories

The properties configuring the needle fall into two general types based on whether they configure the breadth of the needle or its extent from the scale:

Configure the needle shape and position in the across-the-scale dimension, relative to the inner edge of the Graph area. Their values represent the relative part of the breadth of the Graph area in the across-the-scale dimension presented as a decimal fraction of 1 (e.g. _0.2 ), with 0 denoting the inner edge of the graph area and 1 – its outer edge.

Denote settings defined as a relative part of a base value set with the NeedleBreadth property. That relative part is presented as a decimal fraction of 1, for example, if the NeedleBreadth is set to 20 and the NeedleOuterBaseWidth is 0.5 , the actual size of the outer base segment will be 10 pixels (20 x 0.5 = 10).

Property subsets

The full set of the properties applies when you are configuring a custom shape(the NeedleShape property is “Custom” ). To pre-defined shape types, only a subset of these widths and extents apply because drawing these shapes do not require all three basic shapes.

Property subsets per part

Following are the properties you need to use to use to configure the basic parts of a custom needle:

Property subsets per needle shape type

The following table shows which shape configuration properties you need to set when customizing a particular needle shape type. For details on the meaning of the properties and their settings, see Property reference.

Needle shape type Properties

Custom

Needle

  • NeedleBreadth

  • NeedleInnerExtent

  • NeedleInnerPointExtent

  • NeedleInnerPointWidth

  • NeedleOuterBaseWidth

  • NeedleOuterExtent

  • NeedleOuterPointWidth

Rectangle

  • NeedleBreadth

  • NeedleInnerBaseWidth

  • NeedleInnerExtent

  • NeedleOuterBaseWidth

  • NeedleOuterExtent

Trapezoid

  • NeedleBreadth

  • NeedleInnerBaseWidth

  • NeedleInnerExtent

  • NeedleOuterBaseWidth

  • NeedleOuterExtent

Triangle

  • NeedleBreadth

  • NeedleInnerExtent

  • NeedleOuterBaseWidth

  • NeedleOuterExtent

Property reference

The following table explains briefly the properties that configure the needle shape and maps them to the shape types and parts to which they apply. The properties are listed alphabetically.

Property Part Details Applies when NeedleShape is

All

Base width (in pixels) used for defining the width-related properties. The allowed settings are all numeric values greater than 0. Note that values that are too big would make the needle disproportionally large.

  • “Custom”

  • “Needle”

  • “Rectangle”

  • “Trapezoid

  • “Triangle”

Inner

Width Breadth of the Inner base segment of the needle inner edge.

  • “Custom’

  • “Rectangle”

  • “Trapezoid”

Inner

Across-the-scale position of the inner edge of the inner base segment defined as a relative part of the height/width of the Graph area (depending on the orientation) presented as a fraction of 1 (e.g. 0.2).

Together with the NeedleInnerPointExtent property specifies the extent and position across the scale of the Inner part.

  • “Custom”

  • “Needle”

  • “Rectangle”

  • “Trapezoid”

  • “Triangle”

Inner / Middle

Across-the-scale position of:

  • Inner part’s outer edge

  • Middle part’s inner edge

The position is defined as a relative part of the breadth of the Graph area presented as a fraction of 1 (e.g. 0.2).

Together with the NeedleInnerExtent property specifies the extent and position across the scale of the Inner part.

Together with the NeedleOuterPointExtent property specifies the extent and position across the scale of the Middle part. Across-the-scale position of the inner point of the needle (the point …), defined as a relative part of the height/width of the Graph area (depending on the orientation) presented as a fraction of 1 (e.g. 0.2).

  • “Custom”

  • “Needle”

Inner /

Middle

Breadth Width of:

  • Inner part’s outer edge of the needle

  • Middle part’s inner edge.

  • “Custom”

  • “Needle”

Outer

Breadth of the Outer part’s outer edge.

  • “Custom”

  • “Needle”

  • “Rectangle”

  • “Trapezoid”

  • “Triangle”

Inner

Across-the-scale position of the outer base segment defined as a relative part of the height/width of the Graph area (depending on the orientation) presented as a fraction of 1 (e.g. 0.2)

Across-the-scale position of the outer edge of the Outer part defined as a relative part of the breadth of the Graph area presented as a fraction of 1 (e.g. 0.2).Together with the NeedleOuterPointExtent property specifies the extent and position across the scale of the Inner part.

  • “Custom”

  • “Needle”

  • “Rectangle”

  • “Trapezoid”

  • “Triangle

Outer / Middle

Across-the-scale position of:

  • Middle part’s outer edge

  • Outer part’s inner edge

The position is defined as a relative part of the breadth of the Graph area presented as a fraction of 1 (e.g. 0.2).

Together with the NeedleInnerPointExtent property specifies the extent and position across the scale of the Middle part.

Together with the NeedleOuterExtent property specifies the extent and position across the scale of the Outer part. Across-the-scale position of the outer edge of the Middle part defined as a relative part of the height/width of the Graph area (depending on the orientation) presented as a fraction of 1 (e.g. 0.2).

“Custom”

Outer / Middle

Breadth of:

  • Middle part’s outer edge

  • Outer part’s inner edge

  • “Custom”

  • “Needle”

Depends on the shape type

The shape of needle. (The default is “Needle” which defines a rectangular needle body with a triangle point.) The allowed settings are

  • “Custom”

  • Needle ” (default)

  • Rectangle”

  • “Trapezoid

  • Triangle”

Not applicable to the NeedleShape property itself.

Code Examples Summary

Code examples summary chart

The following table lists the code examples included in this topic.

Example Description

This example demonstrates setting the default needle with customize the look-and-feel (brown border, 3 pixels thick, and orange fill).

This example demonstrates defining a custom (butterfly-shaped) needle.

Code Example: Configuring a Basic Needle

Description

This example demonstrates setting the default needle with customize look-and-feel (brown border, 3 pixels thick, and orange fill).

The screenshot below demonstrates how the XamLinearGauge looks as a result of the following settings:

Property Value

“85”

Orange

Brown

3

XamLinearGauge Configuring the Needle 3 17 1.png

Code

Following is the code that implements this example.

In XAML:

<ig:XamLinearGauge x:Name="linearGauge"
               Value="85"
               NeedleBrush="Orange"
               NeedleOutline="Brown"
               NeedleStrokeThickness="3"/>

In C#:

linearGauge.NeedleBrush = new SolidColorBrush(Color.FromRgb(255, 128, 0));
linearGauge.NeedleOutline = new SolidColorBrush(Color.FromRgb(102, 51, 0));
linearGauge.NeedleStrokeThickness = 3;
linearGauge.Value = 85;

Code Example: Configuring a Custom Needle

Description

The screenshot below demonstrates defining a custom (butterfly-shaped) needle as a result of the following settings:

XamLinearGauge Configuring the Needle 4 17 1.png

Code

Following is the code that implements this example.

In XAML:

<ig:XamLinearGauge x:Name="linearGauge"
                     NeedleShape="Custom"
                     Value="50"
                     NeedleInnerExtent=".4"
                     NeedleOuterExtent=".6"
                     NeedleInnerPointExtent="0.1"
                     NeedleOuterPointExtent=".9"
                     NeedleInnerBaseWidth="0"
                     NeedleOuterBaseWidth=".1"
                     NeedleInnerPointWidth=".3"
                     NeedleOuterPointWidth=".35"/>

In C#:

linearGauge.NeedleShape = LinearGraphNeedleShape.Custom;
linearGauge.Value = 50;
linearGauge.NeedleInnerExtent = .4;
linearGauge.NeedleOuterExtent = .6;
linearGauge.NeedleInnerPointExtent = .1;
linearGauge.NeedleOuterPointExtent = .9;
linearGauge.NeedleInnerBaseWidth = 0;
linearGauge.NeedleOuterBaseWidth = .1;
linearGauge.NeedleInnerPointWidth = .3;
linearGauge.NeedleOuterPointWidth = .35;

Related Content

The following topics provide additional information related to this topic.

Topic Purpose

This topic explains, with examples, how to configure the scale of the XamLinearGauge control. This includes positioning the scale inside the control and configuring the scale tick marks and labels.

This topic explains, with code examples, how to configure ranges in the XamLinearGauge control. This includes the number of ranges and their positions, lengths, widths, and formatting.

This topic explains, with code examples, how to configure a background for the linear gauge. This includes setting the background’s size, position, color, and border.