Version

XamLinearGauge Overview

Purpose

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

Introduction

XamLinearGauge summary

The XamLinearGauge control is an Ultimate UI for Xamarin control which allows for visualizing data in the form of a linear gauge. It provides a simple and concise view of a primary value compared against a scale and one or more comparative ranges.

XamLinearGauge 17 1.png

The XamLinearGauge control provides you with the ability to create attractive data presentations and has multiple application usage scenarios.

Main Features

Main features summary

The features of XamLinearGauge include configurable orientation and direction, configurable visual elements, and more. The control has also a built-in support for animated transitions.

Main features summary chart

The following table summarizes the main features of the XamLinearGauge control.

Feature Description

Configurable orientation and direction

The XamLinearGauge control exposes an API for setting the state of its scale’s orientation and direction, so that the look of the gauge can be largely customized. (For details, see the Configuring the Orientation and Direction topic.)

Configurable visual elements

Each of the visual elements of the linear gauge can be configured in several aspects. (For details, see Configurable Visual Elements of XamLinearGauge and Related Properties.)

Animated transitions

The XamLinearGauge control provides built-in support for animation by its TransitionDuration property. The animation effect occurs on loading the control as well as when the value of any of its properties is changed. (For details, see Animated Transitions Configuration.)

Logical areas and Configurable Visual Elements Summary

Logical areas

Each of the areas serves different purpose related to some of the visual elements of the XamLinearGauge control.

  • Reserved area – This area spreads:

    • Along the scale – the Reserved area begins at the edge of the control and ends at the edge of the control.

    • Across the scale

      • In horizontal orientation: the Reserved area begins at the bottom edge of the control and spreads upward as much as the height of the numbering labels is (depending on the size and the other formatting of the font used in the labels)

      • In vertical orientation: the Reserved area begins at the left edge of the control and spreads to the right as much as the width of the numbering labels is (depending on how large the numbers of the measurements of the scale are and the size and the other formatting of the font used in the labels).

The main purpose of the Reserved area is to provide enough space for the numbering labels of the scale at any orientation – horizontal or vertical (The Reserved area automatically re-sizes when the orientation changes in order to accommodate the specific space requirements for displaying the numbering labels in each of the orientations: in horizontal orientation, the area has to fit the labels’ height and in vertical orientation – their maximum width.) This doesn’t mean that you must necessarily place the numbering labels in the Reserved area: actually, you can position the label row across-the-scale anywhere within the Graph area. However, even if you place the label row outside Reserved area, this will have no bearing on the spread and location of the Reserved area itself – it remains where it is, automatically defined through the height/width (depending on the orientation) of the numbering labels.

Another aspect in which the Reserved area is significant is the fact that its inner edge specifies the beginning edge of the Graph area in the across-the-scale dimension. This is important, because this edge serves as a reference mark for the extent-related properties that position some Configurable visual elements and visual elements across the scale. (Positive values for these properties – the most common case – position the visual elements inside the Graph area and negative values – inside the Reserved area.)

  • Graph area – The area for displaying the needle, the tick marks, the ranges, and, optionally, the numbering labels of the linear gauge. All extent-related properties for these visual elements (except for labels) are measured against its edges. The Graph area serves not as a placeholder but as a frame of reference for positioning the scale inside the control (More precisely, for positioning the visual elements of the scale).

Spread of the Graph area:

  • Along the scale – the Graph area begins at the edge of the control and ends at the edge of the control. Both the starting and ending positions of the scale are measured against the starting edge of the Graph area (the left edge at horizontal orientation or bottom edge at vertical orientation).

  • Across the scale – the Graph area begins at the edge of the Reserved area (this is the bottom edge of the Graph area at horizontal orientation or its left edge at vertical orientation). The edge of the Graph area that borders with the Reserved area serves as reference point for the extent-related properties of some of the visual elements of the scale (for positioning these elements across the scale).

Configurable visual elements

The XamLinearGauge control features the following visual elements :

  • Needle – This is the primary measure displayed by the control and is visualized as a bar.

  • Comparative range(s) – The ranges are visual elements that highlight a specified range of values on a scale. Their purpose is to visually communicate the qualitative state of the performance bar measure, illustrating at the same times the degree to which it resides within that state.

  • Tick marks –The tick marks serve as a visual division of the scale into intervals in order to increase the readability of the linear gauge.

    • Major tick marks – The major tick marks are used as primary delimiters on the scale. The frequency they appear at, their extents and style can be controlled by setting the corresponding properties.

    • Minor tick marks – The minor tick marks represent helper tick marks, which might be used to additionally improve the readability of the scale and can be customized in a way similar to the major ones.

  • Scale labels – The labels indicate the measures on the scale.

  • Border – The line visually delimiting the dimensions of the control.

  • Background – The background on which visual elements is placed is configurable in terms of pattern and color.

Configurable Visual Elements and Related Properties

Configurable visual elements and related properties summary

There are several specific aspects in which each element can be configured.

The following table provides an overview of the configurable aspects of the visual elements of the XamLinearGauge control. Further details about the configurable aspects with illustrations and the properties that configure them are available, for each visual element, in the blocks that follow the table:

Visual element Main configurable aspects
  • Position

  • Tick marks

  • Labels

  • Value indicated

  • Width and position

  • Look-and-feel (shape)

  • Number (of ranges in the graph)

  • Length, width, and position

  • Look-and-feel

  • Size and position

  • Look-and-feel

Scale

The following pictures illustrate the scale-related extents, listed in the table below.

Extent positioning the scale within the Graph area Extents configuring the position of the labels
XamLinearGauge Overview 5.png
XamLinearGauge Overview 6.png
Extents configuring the major tick marks along the scale Extents configuring the major tick marks across the scale
XamLinearGauge Overview 7.png
XamLinearGauge Overview 8.png
Extents configuring the minor tick marks across the scale
XamLinearGauge Overview 9.png

The following table maps the configurable aspects related to the scale of the linear gauge to the XamLinearGauge properties that manage them.

Configurable aspects Property Default value

Position

0.05

0.95

Min value

0

Max value

100

Major tick marks

Not set

0

0

0.02

0.2

Defined in the default theme

2.0

Minor tick marks

3.0

0.06

0.2

Defined in the default theme

1.0

Labels

0

Not set

0

0

Defined in the default theme

Needle

The following picture illustrates the needle-related extents, listed in the table below.

XamLinearGauge Overview 10.png

The following table maps the basic configurable aspects related to the needle of the linear gauge to the XamLinearGauge properties that manage them.

Configurable aspects Property Default value

Value indicated

Not set

Breadth

10.0

Fill color

Defined in the default theme

Border color

Defined in the default theme

Border thickness

1.0

Shape

Needle

Comparative ranges

The following picture illustrates the comparative-ranges-related extents, listed in the table below.

XamLinearGauge Overview 11.png

The following table maps the configurable aspects related to the comparative ranges of the linear gauge to the XamLinearGauge properties that manage them.

Configurable aspects Property Default value

Number (of ranges in the graph)

Not set

Length, width, and position

Not set

Not set

Not set

Not set

Not set

Not set

Fill color

Defined in the default theme

Border color

Defined in the default theme

Border thickness

1.0

Background

The following picture illustrates the background-related extents, listed in the table below.

XamLinearGauge Overview 12.png

The following table maps the configurable aspects related to the background of the linear gauge to the XamLinearGauge properties that manage them.

Configurable aspects Property Default value

Spread and position (across the scale)

0

1.0

Color

Defined in the default theme

Border color

Defined in the default theme

Border thickness

2.0

Animated Transitions Configuration

Animated transitions configuration summary

The XamLinearGauge control provides built-in support for animation by its TransitionDuration property. The animation effect occurs on loading the control as well as when the value of any of its properties is changed. By default, animated transitions are disabled. Providing a value in milliseconds for the TransitionDuration property of the control determines the timeframe for swiping the control into view by smoothly visualizing all its visual elements through a slide effect (from bottom-left to top-right). Setting the value to 0 disables the animated transition.

Default Configuration

Default configuration summary

By default, the XamLinearGauge control is oriented horizontally. It displays with a scale starting at 0 and ending at 100. The major tick marks of the control are located at an interval of 10 and the count of minor tick marks between each pair of major tick marks is 4. The background color is white . The border is 2 pixels thick colored in dark grey. No needle or ranges are displayed. Animated transitions are disabled.

The following picture demonstrates a XamLinearGauge displayed with default settings.

XamLinearGauge Overview 13 17 1.png

Requirements

Requirements summary

The XamLinearGauge is a Xamarin.Forms control and a part from the , containing the control itself, it depends on several other . In order for the linear gauge to display a value, the Value property has to be set.

For the full requirements listing, refer to the Adding XamLinearGauge

Related Content

The following topics provide additional information related to this topic.

Topic Purpose

This topic explains how to add the XamLinearGauge control to an Ultimate UI for Xamarin application.

This is a group of topics explaining how to configure the various aspects of the XamLinearGauge control including its orientation and direction and visual elements.

This topic provides reference information about the key classes and properties related to the XamLinearGauge control.