Skip to end of metadata
Go to start of metadata

Crosslight 5 introduces the addition of gauge chart to the Crosslight Charting family. The addition of gauge chart allows you to present and visualize data where the value is within a certain range. This document will help you get started on how to use the gauge chart for iOS and Android platform.

Gauge Element Overview

Crosslight gauge is composed of various UI elements such as Arrow, Title, Major Axis, Minor Axis, Region, Axis Line. Each gauge element corresponds to an object.

The following figure describes the various elements that are contained in the gauge chart.

Using Crosslight Gauge

Crosslight gauge is built upon the MVVM design pattern, so it is recommended that you're already familiar with the pattern. To learn about MVVM, please refer to Understanding Data Binding and MVVM Design Pattern.

To use the Crosslight gauge, just follow these simple steps:

  • Add the required gauge assemblies to your project.
  • Add the GaugeView control to the views in each platform.
  • Configure gauge component model in ViewModel
  • Bind the gauge object model in binding provider.

Add the required Gauge assemblies to your project

First, you need to configure your projects and add the Data Visualization assemblies to your project. To do this, simply use the NuGet extension for Mac or Visual Studio and install the Intersoft.Crosslight.UI.DataVisualization package.

NuGet

To learn more on how to use Crosslight NuGet Packages, see Introduction to Crosslight NuGet Packages.

Your project should look like the following after successful installation.

 

Add the GaugeView control to the views in each platform

On Android platform, all you need to do is just use the GaugeView directly inside your AXML layout, like so:

Android axml

On iOS, you would use the UIGaugeViewController class.

iOS View Controller

Configure Gauge Component Model in ViewModel

The following code shows how to create and configure the gauge component model.

ViewModel

Bind the Gauge Object Model in BindingProvider

After you have the View and ViewModel, just like other Crosslight controls, you will need to bind your control to ViewModel in BindingProvider as follows.

Binding Provider

For more information about the BIndingProvider, check out Understanding Binding Providers.

Run your application, and you should get a similar gauge in your application.

Configuring Gauge Axis

Here are some property that you can use to configuring gauge axis :

  • Length (The length of axis tick)
  • Color (The color of axis tick)
  • Font (The font of the axis text)
  • Margin (The margin of axis tick from axis line)
  • TextMargin (The margin of axis text from axis line)
  • TextPosition (The position of axis text)
  • IsTextVisible
  • IsTickVisible

Suppose you have axis configuration such as code below :

Then you will have a gauge with major and minor axis that look like this :

 

Configuring Gauge Title and Subtitle

Here are some properties that you can use for configuring gauge title and subtitle :

  • Font
  • Text
  • GaugeTitleTextPosition
  • Margin 
  • Number Format (The numeric format that will be used for gauge value)

To use the value of the gauge in gauge title, you can use {value} in your text.

Suppose you have title and subtitle configuration as follows:

Then you will have a gauge with title and subtitle that look like this:

You can change GaugeTitleTextPosition to center, right, bottom, left or top. You can configure title and subtitle margin by configuring its Thickness property. Refer to the example below to learn how to configure title position and margin:

 

 


Configuring Gauge Arrow

Here are some properties that you can use to configuring gauge arrow :

  • Value (value of the gauge)
  • Color (color of the arrow)
  • Path (Path for the arrow)
  • UseCircle (Whether arrow have circle in its core)
  • CircleRadius (The radius of the arrow circle)
  • CircleColor (Color of the arrow circle)
  • CorderColor (Color of the arrow circle's border)

Use this coordinate in generating path for the arrow :

Suppose you have arrow configuration such as code below :

Then you will have a gauge with arrow that look like this :

Suppose you have arrow configuration such as code below :

Then you will have a gauge with arrow that look like this :

Configuring Gauge Region

Here are some property that you can use to configuring gauge region:

  • Minimum
  • Maximum
  • Color
  • Length
  • Margin
  • RegionFillMode

Suppose you have region configuration such as code below :

Then you will have a gauge with region that look like this :

Gauge component model also has property called GaugeRegionStyle that determines if the region style is Fill or Stroke, if GaugeRegionStyle is set to stroke then gauge region will replace axis line of the gauge, to change the width of the axis line you can use AxisLineWidth property of the Gauge component model. Refer to the sample below to learn how to configure gauge region style and axis line width:

You can use Length property of the GaugeRegion to determine the length of the region. Refer to the sample below to learn how to configure gauge region length:

You can use RegionFillMode property of the GaugeRegion component model to determine the style of the region. Refer to the example below to learn how to configure gauge region fill mode:

Blend:

Radial:

Solid:

Configuring gauge degree and start degree

To change gauge degree and start degree, you just need to modify the value of Degree and StartDegree property of Gauge component model. Degree is the degree of Gauge, where StartDegree is the start degree of Gauge (0 degree is at the bottom). By default, value of degree is 300 and value of start degree is double.Nan. When the value of start degree is double.Nan, Crosslight Gauge will determine its start degree by (360 - degree) / 2. Refer to the example below to learn how to configure circular gauge degree and start degree:

Configuring Start and End Text

You can give custom string as start and end value of your gauge by configuring StartText and EndText property of Gauge component model. Refer to the code below to learn how to configure gauge start and end text:

When they are configured, you'll get the following result.

Invert Gauge Value

You can invert your gauge value just by setting IsValueInverted property of Gauge component model to true. Refer to the code below to learn how to invert gauge value:

Here's how it looks like when the value is inverted.

Configuring Animation Duration and Easing Function

You can change animation duration of Crosslight gauge by configuring AnimationDuration value of Gauge component model.

You can choose AnimationEasingFunction for your gauge from these options:

  • Linear (Zero Acceleration)
  • EaseOut (Accelerate Animation)
  • EaseIn (Decelerate Animation)

Refer to the code below to learn how to configure gauge animation duration and easing function:


Samples

To see Crosslight Gauge in action, please check out the comprehensive gauge samples here