This topic explains, with code examples, how to configure the needle of the {LinearGaugeName}™ control. This includes the value indicated by the needle, its width, position, and formatting.
The following topics are prerequisites to understanding this topic:
| Topic | Purpose |
|---|---|
This topic provides conceptual information about the {LinearGaugeName} control including its main features, minimum requirements, and user functionality. |
This topic contains the following sections:
-
Code Example: Configuring a Basic Needle
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) pick:[sl,wpf="and providing a tooltip"] .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:
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.
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).
The following table explains briefly the configurable aspects of {LinearGaugeName} 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 pick:[sl,wpf="(for displaying in the"] pick:[sl,wpf=" tooltip"] pick:[sl,wpf=")"] |
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 |
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 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.
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:
-
Extent-type properties ( NeedleInnerExtent, NeedleInnerPointExtent, NeedleOuterPointExtent, NeedleOuterExtent)
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.
-
Width-related properties ( NeedleInnerBaseWidth, NeedleOuterBaseWidth, NeedleInnerPointWidth, NeedleOuterPointWidth)
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).
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.
Following are the properties you need to use to use to configure the basic parts of a custom needle:
-
Outer part properties:
-
NeedleOuterPointExtent – common for the Outer and Middle basic parts
-
NeedleOuterPointWidth – common for the Outer and Middle basic parts
-
Middle part properties:
-
NeedleOuterPointExtent – common for the Outer and Middle basic parts
-
NeedleInnerPointExtent – common for the Inner and Middle basic parts
-
NeedleOuterPointWidth – common for the Outer and Middle basic parts
-
NeedleInnerPointWidth – common for the Inner and Middle basic parts
-
-
Inner part properties:
-
NeedleInnerPointExtent – common for the Inner and Middle basic parts
-
NeedleInnerPointWidth – common for the Inner and Middle basic parts
-
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 |
|
Rectangle |
|
Trapezoid |
|
Triangle |
|
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. |
|
|
Inner |
Width Breadth of the Inner base segment of the needle inner edge. |
|
|
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 |
|
|
Inner / Middle |
Across-the-scale position of:
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 Together with the |
|
|
Inner / Middle |
Breadth Width of:
|
|
|
Outer |
Breadth of the Outer part’s outer edge. |
|
|
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 |
|
|
Outer / Middle |
Across-the-scale position of:
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 Together with the |
“Custom” |
|
Outer / Middle |
Breadth of:
|
|
|
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
|
Not applicable to the |
The following table lists the code examples included in this topic.
| Example | Description |
|---|---|
Configuring a Basic Needle |
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. |
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 {LinearGaugeName} looks as a result of the following settings:
| Property | Value |
|---|---|
“85” |
|
“ Orange ” |
|
“ Brown ” |
|
“ 3 ” |
The screenshot below demonstrates defining a custom (butterfly-shaped) needle as a result of the following settings:
| Property | Value |
|---|---|
Custom |
|
50 |
|
0 |
|
0.3 |
|
0.35 |
|
0.1 |
|
0.4 |
|
0.1 |
|
0.9 |
|
0.6 |
The following topics provide additional information related to this topic.
| Topic | Purpose |
|---|---|
This topic explains, with examples, how to configure the scale of the {LinearGaugeName} 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 {LinearGaugeName} 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. |