Gauge class

Specifies the operation a layer is performed once the user drags it. The Layer.OnDrag property specifies the operation to perform when the user drags a layer, and uses the values of Gauge.OnDragLayerEnum enumeration.

Each OnDragLayerEnum property can be specified in one of the following ways:

• A numeric value.
• A single enumeration constant.
• A case-insensitive partial string containing a name that matches the enumeration constants.

For instance, the string "rotate" is equivalent to the numeric value 2, or to the enumeration constant exDoRotate.

The type field holds the full name of the object, since constructor.name can differ in minimized or obfuscated code. This field is never altered by the control itself, so it can be reliably used to verify the object's type. It is particularly useful when multiple versions of a control exist or when you need to check the type without depending on constructor.name, which may be inconsistent in some scenarios, such as minified code. The Gauge.type member always returns "Gauge"

console.log(exontrol.Gauge.type); // logs "Gauge"

The version field defines the version of the control. Each release of the control has a different version number, so you can use this field to check the control's version and ensure that it supports the features you want to use. The version field is especially useful when you have multiple versions of the control, or when you want to check the version of the control without relying on other properties or methods that may differ between versions. The current version is 5.4

console.log(exontrol.Gauge.version); // displays the version of the control, for instance "5.2"

The vAlpha field defines a threshold (0–255) used to determine whether a pixel is considered visible based on its alpha (transparency) value.

In an RGBA pixel, the alpha channel (A) controls opacity:

• 0 = fully transparent (invisible)
• 255 = fully opaque (completely visible)

The vAlpha value acts as a cutoff:

• Any pixel with alpha ≥ vAlpha is treated as visible
• Any pixel with alpha < vAlpha is treated as transparent (ignored)

For example:

• If vAlpha = 0, all pixels are visible (even fully transparent ones)
• If vAlpha = 255, only fully opaque pixels are visible
• If vAlpha = 128, only pixels that are at least 50% opaque are considered visible

This field is useful when you need to ignore partially transparent pixels and work only with pixels that meet a certain visibility threshold. By default, vAlpha is set to 128, meaning that only pixels that are at least 50% opaque will be treated as visible.

The Cursors property defines the mouse cursor to be displayed when pointing over a part of the control. The Cursors property allows you to define different cursor styles for various parts of the control, enhancing the user experience by providing visual feedback based on the context of interaction. For example, you can set a "pointer" cursor when hovering over clickable areas, or a "move" cursor when hovering over draggable layers. This customization helps users understand what actions are possible and improves the overall usability of the control.

The format of the property is:

"cursor(part),cursor(part),..."

where:

• "cursor", defines the CSS mouse cursor to display while cursor hovers the part
• "part", defines the name of the part the cursor is applied on (as defined bellow)

The "cursor" can be any of the following:

Cursor	Description
"alias"	indicates a shortcut or alias will be created
"all-scroll"	indicates scrolling in any direction
"auto"	lets the browser decide the cursor based on context
"cell"	indicates a table cell
"col-resize"	indicates a column can be resized horizontally
"context-menu"	indicates a context menu is available
"copy"	indicates something will be copied
"crosshair"	a precise crosshair cursor
"default"	the default arrow cursor
"e-resize"	resize east (right edge)
"ew-resize"	resize horizontally
"grab"	indicates an item can be grabbed
"grabbing"	indicates an item is being grabbed
"help"	indicates help information is available
"move"	indicates something can be moved
"n-resize"	resize north (top edge)
"ne-resize"	resize northeast (top-right corner)
"nesw-resize"	resize along the northeast–southwest axis
"no-drop"	indicates dropping is not permitted
"not-allowed"	indicates the action is not allowed
"ns-resize"	resize vertically
"nw-resize"	resize northwest (top-left corner)
"nwse-resize"	resize along the northwest–southeast axis
"pointer"	the pointer cursor (a hand with a pointing finger)
"progress"	indicates background processing
"row-resize"	indicates a row can be resized vertically
"s-resize"	resize south (bottom edge)
"se-resize"	resize southeast (bottom-right corner)
"sw-resize"	resize southwest (bottom-left corner)
"text"	the text selection cursor (I-beam)
"url(...)"	uses a custom cursor image (with optional fallback)
"vertical-text"	the vertical text selection cursor
"w-resize"	resize west (left edge)
"wait"	indicates the program is busy
"zoom-in"	indicates zooming in
"zoom-out"	indicates zooming out

The "part" can be any of the following:

Part	Description
"anchor" (hyperlink)	defines the mouse-cursor when the mouse pointer hovers the anchor (the <a> ex-HTML part marks an anchor or hyperlink element) (@since 2.2)
"dable" (selectable and dragable layer)	defines the cursor for selectable and dragable layers
"sable" (selectable layer)	defines the cursor for selectable layers

null {null}, no mouse cursor is provided.
"crosshair(dable)" {string}, indicates that the "crosshair" mouse cursor is shown once the cursor hovers any "dable" (selectable and dragable) layers

The Debug property shows the control in debug-mode. In debug-mode, the layers are shown in perspective with different colors and opacity, so you can easily identify the layers' boundaries, positions, and rotations. This is useful when you design the layers of the control to ensure that they are properly aligned and sized. By default, the Debug property is set to false, which means that the layers are shown in normal-mode without any special coloring or opacity.

false {boolean}, shows the layers in normal-mode
true {boolean}, shows the layers in debug-mode

The FormatText property defines the format used to display labels or captions on the control. It is a bitwise combination of flags that control text alignment, word-breaking, tab expansion, and other rendering options. For example, you can align text to the center, enable word-breaking for long captions, or display text on a single line. The available flags are defined in the exontrol.DrawTextFormatEnum type and can be combined to achieve the desired text formatting.

The exontrol.DrawTextFormatEnum type support the following flags:

• exTextAlignTop (0x00), justifies the text to the top of the rectangle
• exTextAlignLeft (0x00), aligns text to the left
• exTextAlignCenter (0x01), centers text horizontally in the rectangle
• exTextAlignRight (0x02), aligns text to the right
• exTextAlignVCenter (0x04), centers text vertically
• exTextAlignBottom (0x08), justifies the text to the bottom of the rectangle.
• exTextAlignMask (0x0F), specifies the mask for text's alignment.
• exTextWordBreak (0x10), breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-line feed sequence also breaks the line. If this is not specified, output is on one line.
• exTextSingleLine (0x20), displays text on a single line only. Carriage returns and line feeds do not break the line.
• exTextExpandTabs (0x40), expands tab characters. The default number of characters per tab is eight.
• exPlainText (0x80), treats the text as plain text.
• exTextNoClip (0x0100), draws without clipping.
• exHTMLTextNoColors (0x0200), ignores the and tags.
• exTextCalcRect (0x0400), determines the width and height of the text.
• exHTMLTextNoTags (0x0800), ignores all HTML tags.
• exTextPathEllipsis (0x4000), for displayed text, replaces characters in the middle of the string with ellipses so that the result fits in the specified rectangle. If the string contains backslash (\) characters, exTextPathEllipsis preserves as much as possible of the text after the last backslash.
• exTextEndEllipsis (0x8000), for displayed text, if the end of a string does not fit in the rectangle, it is truncated and ellipses are added. If a word that is not at the end of the string goes beyond the limits of the rectangle, it is truncated without ellipses.
• exTextWordEllipsis (0x040000), truncates any word that does not fit in the rectangle and adds ellipses.

null {null}, centers the caption
32 or exontrol.DrawTextFormatEnum.exTextSingleLine {number}, defines a single-line caption
0x2A or exontrol.DrawTextFormatEnum.exTextSingleLine | exontrol.DrawTextFormatEnum.exTextAlignRight | exontrol.DrawTextFormatEnum.exTextAlignBottom {number}, defines a single-line caption right/bottom-aligned

The LayerAutoSize property defines the index or the key of the layer that determines the size used to display all layers (scaled). The size of a layer is determined by its background picture (if provided). The LayerAutoSize property has no effect if the referenced layer has no background picture/image. The Back property of a layer can be used to specify its background picture/image, so if you set the LayerAutoSize property to the index or key of a layer with a background picture/image, all layers are resized and scaled based on that layer's background picture/image. For instance, if you set the LayerAutoSize property to "back", and the layer with the key "back" has a background picture/image, all layers are resized and scaled based on that background picture/image. Setting the LayerAutoSize property to -1 specifies that no layer is resized, and they are shown as provided. By default, the LayerAutoSize property is set to 0, which means that all layers are resized and scaled based on the first layer's picture/image (the layer with index 0).

-1 {number}, specifies that no layer is resized, and they are shown as provided
0 {number}, specifies that all layers are resized and scaled based on the first-layer's picture/image (the layer with the index 0)
"back" {string}, specifies that all layers are resized and scaled based on image/picture of the layer with the key "back"

The LayerDragAny property defines the layer to drag (rotate, move or rota-move) once the user clicks anywhere on the control. The Layer.OnDrag property defines the transformation of the layer (move, rotate, or rotamove) once the user clicks and drags it. For example, suppose the control has a draggable layer such as a "needle" or "knob". By using the LayerDragAny property, you can specify that this layer will be dragged (rotated, moved, or swept) when the user clicks anywhere on the control. This means that the user doesn't have to click exactly on the layer to drag it, but can click anywhere on the control to drag that specific layer. The LayerDragAny property is useful when you want to make it easier for the user to interact with a specific layer, especially if that layer is small or hard to click on. If the cursor hovers over a draggable layer, the LayerDragAny property is ignored, and the hovered layer is dragged instead. By default, the LayerDragAny property is set to -1, which means that it has no effect and the user has to click on a draggable layer to drag it.

-1 {number}, specifies that the user has to click on a draggable layer to drag it (default)
0 {number}, indicates that the layer with the index 0 is dragged (once the user clicks anywhere on the control)
"needle" {string}, indicates that the layer with the key "needle" is dragged (once the user clicks anywhere on the control)

The LayerOfValue property defines the index or the key of the layer whose value determines the Gauge.Value property (control's value). Each layer can have its own value, such as a rotation angle or an offset, so the LayerOfValue property defines the layer whose value is used as the control's value. For instance, the "value" keyword within the format-expressions of properties of the Clip object (e.g. [clip.x=value]) uses the Gauge.Value property as the value, so the LayerOfValue property specifies the layer whose value is used. The Layer.Value property defines the value of the layer, which can be the offset used to move the layer, the angle used to rotate the layer, or any other value interpreted by the layer based on its configuration. By default, the LayerOfValue property is -1, meaning the control's value is taken from the top-most visible layer that has the Layer.OnDrag property defined (i.e., the last visible, selectable, and draggable layer). In general, multiple layers can be visible, but typically only one defines Layer.OnDrag, so the control's value is determined by that layer.

-1 {number}, the top-most visible layer that has the Layer.OnDrag property defined defines the control's value
0 {number}, specifies that the layer with the index 0 defines the control's value
"hour" {string}, specifies that the layer with the key "hour" defines the control's value

The Layers property defines the layers of the control. Imagine that if you want to define a clock control with three layers: a background image of a clock face, a layer for the hour hand, and a layer for the minute hand. You could use the Layers property to specify the background image for the clock face and set the appropriate flags for each layer to control their visibility and interactivity. Each layer is defined by its background (back) and a set of flags (between square brackets) that specify the layer's key, visibility, position, selectability, foreground, and other attributes. By defining layers in this way, you can create complex visual arrangements and interactions within the control, such as stacking images, adding captions, or controlling the visibility and interactivity of each layer. The string-based configuration allows you to easily set up multiple layers with different properties in a concise format.

The Layers property defines the control's layers as follows:

1. string-representation (separated by comma character), result of Layers.Save() method, where the format of the string is:

   "back[flag=value]...[flag=value],...,back[flag=value]...[flag=value],..."

   where:
   • "back", (equivalent of Layer.Back property) could be:
     • "" {empty string} (no layer background provided)
     • "image" {picture's name}, defines the name of a picture previously added using the exontrol.HTMLPicture.Add(name,...) method. For instance, "pic" indciates that the HTML Picture named "pic" is stretched on the layer's background.
     • "color" {string}, indicates a CSS color to be displayed on the layer's background. For instance, "red", "rgba(255,0,0,1)", "#FF0000" indicates a layer full-filed with a solid red-color.

   The flag can be any of the following:

   Flag	Description	Sample
   [a]	rotation angle in degree. Angle 0 is considered the 12 o'clock direction, and it increases clockwise, so 90 degrees is considered the 3 o'clock direction, 180 degrees the 6 o'clock direction, and 270 degrees (or -90 degrees) the 9 o'clock direction. A positive value rotates the layer clockwise, while a negative value rotates it counter-clockwise (equivalent of Layer.RotateAngle property)	[a=90]
   [a2v]	converts rotation angle to value using a format-expression, where "value" keyword represents the Layer.Value property, so the Layer.Value property is calculated based on the rotation angle. For instance, [a2v=value/360*100] means that the value is calculated as a percentage of the rotation angle, where 0 degree corresponds to 0% and 360 degrees corresponds to 100%. This flag is useful when you want to link the layer's value to its rotation angle, such as in a gauge control where the needle's position (rotation) represents a certain value (equivalent of Layer.RotateAngleToValue property)	[a2v=value/360*100]
   [aValid]	validates, limits or snaps the rotation angle of the layer, using a format-expression, where "value" keyword represents the Layer.Value property. For instance, if you want to snap the rotation angle of the layer to multiples of 5 degrees, you can set the rotateAngleValid field to "round(value/5)*5" (equivalent of Layer.RotateAngleValid property)	[aValid=value<90?value:90]
   [brightness.blue]	adjusts the blue channel brightness using a percentage value or a format-expression, where "value" keyword represents the Layer.Value property. For instance, [brightness.blue=value] means that the blue channel brightness is directly linked to the layer's value, so as the value changes, the brightness of the blue channel will adjust accordingly (equivalent of LayerColorAdjustment.Blue property, Brightness property)	[brightness.blue=100-value]
   [brightness.green]	adjusts the green channel brightness using a percentage value or a format-expression, where "value" keyword represents the Layer.Value property. For instance, [brightness.green=value] means that the green channel brightness is directly linked to the layer's value, so as the value changes, the brightness of the green channel will adjust accordingly (equivalent of LayerColorAdjustment.Green property, Brightness property)	[brightness.green=100]
   [brightness.red]	adjusts the red channel brightness using a percentage value or a format-expression, where "value" keyword represents the Layer.Value property. For instance, [brightness.red=value] means that the red channel brightness is directly linked to the layer's value, so as the value changes, the brightness of the red channel will adjust accordingly (equivalent of LayerColorAdjustment.Red property, Brightness property)	[brightness.red=100]
   [cLayer]	defines the index or the key of the layer used as a reference for the layer's rotation center. For instance, [cLayer=-1] means that the rotation center is defined relative to the layer itself, so it remains fixed regardless of any movement or rotation of other layers. This flag is useful when you want to create complex interactions between layers, such as having one layer rotate around another layer or around a fixed point on the control (equivalent of Layer.RotateCenterLayer property)	[cLayer=-1]
   [clip]	specifies the type of the clipping region the current layer supports as "Rect","RoundRect","Ellipse" or "Pie". Once the clip type is specified, you can use the other clip-related flags to define the size, position, and shape of the clipping region. For instance, if you set [clip=Ellipse], you can then specify the ellipse's X and Y radius using [clip.radiusX] and [clip.radiusY], as well as its center position using [clip.xCenter] and [clip.yCenter] (equivalent of LayerClip.Clip property)	[clip=Ellipse]
   [clip.height]	defines the height of the clipping region, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.height=120] means that the clipping region has a fixed height of 120 pixels, while [clip.height=value] means that the clipping region's height is directly linked to the clip's value, so as the value changes, the height of the clipping region will adjust accordingly (equivalent of LayerClip.Height property)	[clip.height=120]
   [clip.left]	defines the left position of the clipping region, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.left=120] means that the clipping region's left edge is positioned at 120 pixels from the left edge of the layer, while [clip.left=value] means that the left position of the clipping region is directly linked to the clip's value, so as the value changes, the left position of the clipping region will adjust accordingly (equivalent of LayerClip.Left property)	[clip.left=120]
   [clip.radiusX]	defines the X radius of the clipping region for ellipse or pie clip types, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.radiusX=120] means that the ellipse's X radius is fixed at 120 pixels, while [clip.radiusX=value] means that the ellipse's X radius is directly linked to the clip's value, so as the value changes, the X radius of the ellipse will adjust accordingly (equivalent of LayerClip.RadiusX property)	[clip.radiusX=128]
   [clip.radiusY]	defines the Y radius of the clipping region for ellipse or pie clip types, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.radiusY=120] means that the ellipse's Y radius is fixed at 120 pixels, while [clip.radiusY=value] means that the ellipse's Y radius is directly linked to the clip's value, so as the value changes, the Y radius of the ellipse will adjust accordingly (equivalent of LayerClip.RadiusY property)	[clip.radiusY=128]
   [clip.roundX]	defines the round rect X radius of the clipping region for round rect clip type, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.roundX=120] means that the round rect's X radius is fixed at 120 pixels, while [clip.roundX=value] means that the round rect's X radius is directly linked to the clip's value, so as the value changes, the X radius of the round rect will adjust accordingly (equivalent of LayerClip.RoundRadiusX property)	[clip.roundX=16]
   [clip.roundY]	defines the round rect Y radius of the clipping region for round rect clip type, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.roundY=120] means that the round rect's Y radius is fixed at 120 pixels, while [clip.roundY=value] means that the round rect's Y radius is directly linked to the clip's value, so as the value changes, the Y radius of the round rect will adjust accordingly (equivalent of LayerClip.RoundRadiusY property)	[clip.roundY=16]
   [clip.start]	defines the start angle of the clipping region for pie clip type, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.start=120] means that the pie's start angle is fixed at 120 degrees, while [clip.start=value] means that the pie's start angle is directly linked to the clip's value, so as the value changes, the start angle of the pie will adjust accordingly (equivalent of LayerClip.StartAngle property)	[clip.start=-45]
   [clip.sweep]	defines the sweep angle of the clipping region for pie clip type, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.sweep=120] means that the pie's sweep angle is fixed at 120 degrees, while [clip.sweep=value] means that the pie's sweep angle is directly linked to the clip's value, so as the value changes, the sweep angle of the pie will adjust accordingly (equivalent of LayerClip.SweepAngle property)	[clip.sweep=45]
   [clip.top]	defines the top position of the clipping region, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.top=120] means that the clipping region's top edge is positioned at 120 pixels from the top edge of the layer, while [clip.top=value] means that the top position of the clipping region is directly linked to the clip's value, so as the value changes, the top position of the clipping region will adjust accordingly (equivalent of LayerClip.Top property)	[clip.top=120]
   [clip.value]	value used for clip expressions as it can be a hard-coded value or the Gauge.Value property if not specified. For instance, if you set [clip.value=50], the "value" keyword used in other clip-related expressions will be replaced by 50 (equivalent of LayerClip.Value property)	[clip.value=50]
   [clip.width]	defines the width of the clipping region, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.width=120] means that the clipping region has a fixed width of 120 pixels, while [clip.width=value] means that the clipping region's width is directly linked to the clip's value, so as the value changes, the width of the clipping region will adjust accordingly (equivalent of LayerClip.Width property)	[clip.width=120]
   [clip.x]	defines the X offset of the clipping region, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.x=120] means that the clipping region is offset by 120 pixels from the left edge of the layer, while [clip.x=value] means that the X offset of the clipping region is directly linked to the clip's value, so as the value changes, the X offset of the clipping region will adjust accordingly (equivalent of LayerClip.OffsetX property)	[clip.x=120]
   [clip.xCenter]	defines the center X position of the clipping region, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.xCenter=120] means that the clipping region's center is positioned at 120 pixels from the left edge of the layer, while [clip.xCenter=value] means that the center X position of the clipping region is directly linked to the clip's value, so as the value changes, the center X position of the clipping region will adjust accordingly (equivalent of LayerClip.CenterX property)	[clip.xCenter=128]
   [clip.y]	defines the Y offset of the clipping region, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.y=120] means that the clipping region is offset by 120 pixels from the top edge of the layer, while [clip.y=value] means that the Y offset of the clipping region is directly linked to the clip's value, so as the value changes, the Y offset of the clipping region will adjust accordingly (equivalent of LayerClip.OffsetY property)	[clip.y=-120]
   [clip.yCenter]	defines the center Y position of the clipping region, using a format-expression that supports "value" (specifies the Clip.Value if specified otherwise the Gauge.Value property), "width" or "lwidth" (indicates the width in pixels of the layer), "height" or "lheight" (indicates the height in pixels of the layer) keywords. For instance, [clip.yCenter=120] means that the clipping region's center is positioned at 120 pixels from the top edge of the layer, while [clip.yCenter=value] means that the center Y position of the clipping region is directly linked to the clip's value, so as the value changes, the center Y position of the clipping region will adjust accordingly (equivalent of LayerClip.CenterY property)	[clip.yCenter=128]
   [contrast.blue]	adjusts the blue channel contrast using a percentage value or a format-expression, where "value" keyword represents the Layer.Value property. For instance, [contrast.blue=100-value] means that the blue channel contrast is inversely linked to the layer's value, so as the value increases, the contrast of the blue channel decreases accordingly (equivalent of LayerColorAdjustment.Blue property, Contrast property)	[contrast.blue=100-value]
   [contrast.green]	adjusts the green channel contrast using a percentage value or a format-expression, where "value" keyword represents the Layer.Value property. For instance, [contrast.green=100-value] means that the green channel contrast is inversely linked to the layer's value, so as the value increases, the contrast of the green channel decreases accordingly (equivalent of LayerColorAdjustment.Green property, Contrast property)	[contrast.green=100-value]
   [contrast.red]	adjusts the red channel contrast using a percentage value or a format-expression, where "value" keyword represents the Layer.Value property. For instance, [contrast.red=100-value] means that the red channel contrast is inversely linked to the layer's value, so as the value increases, the contrast of the red channel decreases accordingly (equivalent of LayerColorAdjustment.Red property, Contrast property)	[contrast.red=100-value]
   [defA]	default rotation angle in degree. Angle 0 is considered the 12 o'clock direction, and it increases clockwise, so 90 degrees is considered the 3 o'clock direction, 180 degrees the 6 o'clock direction, and 270 degrees (or -90 degrees) the 9 o'clock direction. A positive value rotates the layer clockwise, while a negative value rotates it counter-clockwise (equivalent of Layer.DefaultRotateAngle property)	[defA=45]
   [defX]	default x-offset of the layer. The layer's actual x-offset is the sum of left, defaultOffsetX, and offsetX, while the actual y-offset is the sum of top, defaultOffsetY, and offsetY. For instance, if you set the defaultOffsetX field to 10, the offsetX field to 5, the layer is shown with a total x-offset of 15 pixels from the position specified by the left field (equivalent of Layer.DefaultOffsetX property)	[defX=-32]
   [defY]	default y-offset of the layer. The layer's actual y-offset is the sum of top, defaultOffsetY, and offsetY, while the actual x-offset is the sum of left, defaultOffsetX, and offsetX. For instance, if you set the defaultOffsetY field to 10, the offsetY field to 5, the layer is shown with a total y-offset of 15 pixels from the position specified by the top field (equivalent of Layer.DefaultOffsetY property)	[defY=-32]
   [drag]	defines the transformation of the layer (move, rotate, rota-move) once the user drags it. For instance, if you set the drag flag to "move", the layer is moved according to the mouse movement once the user drags it, while if you set it to "rotate", the layer is rotated according to the mouse movement once the user drags it (equivalent of Layer.OnDrag property)	[drag=rotate]
   [fore]	defines a format expression to display the layer's ex-HTML caption in the foreground of the layer, where "value" keyword represents the Layer.Value property, so the caption is calculated based on the value. For instance, [fore=round(value)] means that the caption is calculated as the rounded value of the layer's value, so if the layer's value is 15.6, the caption becomes 16 (equivalent of Layer.Fore property)	[fore=round(value)]
   [fore.front]	shows the layer's ex-HTML caption in front or back of the layer. For instance, [fore.front=0] means that the layer's caption is shown behind the layer, so it is partially or fully hidden based on the layer's background (equivalent of front flag of Layer.ForeOpt property)	[fore.front=0]
   [fore.tfi]	defines the layer's font attributes (font name, size, color, and style). For instance, [fore.tfi=bold 14 Arial <fgcolor red>] means that the layer's caption is shown in bold 14px Arial font with red color (equivalent of tfi flag of Layer.ForeOpt property)	[fore.tfi=bold]
   [fore.format]	specifies the format of the text drawn in the layer's foreground. For instance [fore.format=single,right,bottom] means that the layer's caption is shown as a single line right/bottom-aligned (equivalent of format flag of Layer.ForeOpt property)	[fore.format=single,right,bottom]
   [fore.left]	shifts the layer's caption using a hard-coded value or a value calculated from a format-expression, where "twidth" (indicates the caption's width in pixels), "theight" (indicates the caption's height in pixels), "width" (indicates the layer's width) in pixels and "height" indicates the control's height in pixels. For instance, [fore.left=16] means that the layer's caption is shifted 16 pixels from its default position (equivalent of left flag of Layer.ForeOpt property)	[fore.left=16]
   [fore.top]	shifts the layer's caption using a hard-coded value or a value calculated from a format-expression, where "twidth" (indicates the caption's width in pixels), "theight" (indicates the caption's height in pixels), "width" (indicates the layer's width) in pixels and "height" indicates the control's height in pixels. For instance, [fore.top=16] means that the layer's caption is shifted 16 pixels from its default position (equivalent of top flag of Layer.ForeOpt property)	[fore.top=16]
   [fore.width]	defines the maximum width of the layer's caption using a hard-coded value or a value calculated from a format-expression, where "twidth" (indicates the caption's width in pixels), "theight" (indicates the caption's height in pixels), "width" (indicates the layer's width) in pixels and "height" indicates the control's height in pixels. For instance, [fore.width=100] means that the layer's caption is shown with a maximum width of 100 pixels, so if the caption exceeds 100 pixels in width, it is wrapped to multiple lines or truncated based on the formatText flag (equivalent of width flag of Layer.ForeOpt property)	[fore.width=100]
   [fore.height]	defines the maximum height of the layer's caption using a hard-coded value or a value calculated from a format-expression, where "twidth" (indicates the caption's width in pixels), "theight" (indicates the caption's height in pixels), "width" (indicates the layer's width) in pixels and "height" indicates the control's height in pixels. For instance, [fore.height=100] means that the layer's caption is shown with a maximum height of 100 pixels, so if the caption exceeds 100 pixels in height, it is wrapped to multiple lines or truncated based on the formatText flag (equivalent of height flag of Layer.ForeOpt property)	[fore.height=100]
   [grayscale]	grayscale level of the layer, as a percent value or a format-expression, where "value" keyword represents the Layer.Value property, so the grayscale level of the layer is calculated based on the value. For instance, "value" expression means that the grayscale level is equal to the value of the layer, so if you set the layer's value to 0, it is shown in full color, while if you set it to 100, it is shown in full grayscale (equivalent of Layer.Grayscale property)	[grayscale=100]
   [height]	height of the layer using format-expression, where "width" indicates the control's width in pixels and "height" indicates the control's height in pixels. For instance, "height/4" expression sets the layer's height to a quarter of the control's height (equivalent of Layer.Height property)	[height=height/4]
   [idem]	synchronizes offset/rotation across layers. For instance, "knob,knob2", once you move or rotate one of the layers with key "knob" or "knob2", the other layer is moved or rotated as well, to ensure that both layers have the same offset and rotation angle. The rotateAngle, offsetX, and offsetY fields of all layers included in the idem group are set to the same value, which is the value of the layer that is moved or rotated (equivalent of Layer.Idem property)	[idem=knob,knob2]
   [key]	defines the key of the layer, which is used to identify the layer and reference it from other layers. For instance, "hourHand", "minuteHand", and "secondHand" are keys that can be used to identify the layers of a clock control, so you can set the hour hand's rotation angle based on the current hour, the minute hand's rotation angle based on the current minute, and the second hand's rotation angle based on the current second (equivalent of Layer.Key property)	[key=needle]
   [left]	left horizontal offset using format-expression, where "width" indicates the control's width in pixels and "height" indicates the control's height in pixels. For instance, "width/2" expression places the layer at the horizontal middle of the control (equivalent of Layer.Left property)	[left=width/2]
   [o2v]	converts the current x- and y-offset to a value using a format-expression, where "x" and "y" keywords represent the layer's x- and y-offset respectively. For instance, "(x+y)/2" expression calculates the value as the sum of the x-offset and half of the y-offset, so if you set the layer's x-offset to 10 and y-offset to 20, the value becomes 15 (equivalent of Layer.OffsetToValue property)	[o2v=x+y/2]
   [pos]	defines the z-order position of the layer(0-based). For instance, if you have three layers and you set the pos flag of one of the layers to 0, that layer is shown at the bottom, while if you set it to 2, that layer is shown at the top (equivalent of Layer.Position property)	[pos=0]
   [rotateclip]	rotates clipping region along with the layer. For instance, if you set the rotateclip flag to 1 for a layer with a pie clipping region, when you rotate the layer, the pie clipping region rotates as well, so the visible part of the layer changes as it rotates. This flag is useful when you want to create dynamic visual effects where the visibility of the layer changes based on its rotation (equivalent of Layer.RotateClip property)	[rotateclip=1]
   [sel]	makes the layer selectable or not. The user can not move or rotate the layer using mouse if the layer is not selectable. Setting the sel flag to 0 makes the layer not selectable, while setting it to 1 makes the layer selectable (equivalent of Layer.Selectable property)	[sel=0]
   [top]	top vertical offset using format-expression, where "width" indicates the control's width in pixels and "height" indicates the control's height in pixels. For instance, "height/2" expression places the layer at the vertical middle of the control (equivalent of Layer.Top property)	[top=height/2]
   [transparency]	transparency of the layer, as a percent value or a format-expression, where "value" keyword represents the Layer.Value property, so the transparency of the layer is calculated based on the value. For instance, "100-value" expression makes the layer more transparent as the value increases, so if you set the layer's value to 0, it is fully opaque, while if you set it to 100, it is fully transparent (equivalent of Layer.Transparency property)	[transparency=100-value]
   [value]	defines the value of the layer, which can be the offset to move the layer, the angle to rotate the layer. For instance, 15 may shift the layer 15 pixels from its default position, or rotate the layer 15 degrees from its default angle, depending on how the layer is configured to interpret the value (equivalent of Layer.Value property)	[value=15]
   [vis]	shows or hides the layer. Setting the vis flag to 0 hides the layer, while setting it to 1 shows the layer (equivalent of Layer.Visible property)	[vis=0]
   [v2a]	converts value to rotation angle using a format-expression, where "value" keyword represents the Layer.Value property, so the Layer.Value property is calculated based on the value. For instance, "value/100*360" expression remaps the layer's value in a 0 - 100 range to a rotation angle in a 0 - 360 range, so if you set the layer's value to 25, it is rotated 90 degrees, and if you rotate the layer 180 degrees, its value becomes 50 (equivalent of Layer.ValueToRotateAngle property)	[v2a=value/100*360]
   [v2x]	converts value to x-offset, using a format-expression, where "value" keyword represents the Layer.Value property, so the x-offset of the layer is calculated based on the value. For instance, "(value=0)?0:48", means that if the layer's value is 0, the x-offset is 0, otherwise it is 48 pixels. This flag is useful when you want to link the layer's horizontal position to its value, such as in a switch control where the knob's position (x-offset) represents the on/off state (value) of the switch (equivalent of Layer.ValueToOffsetX property)	[v2x=(value=0)?0:48]
   [v2y]	converts value to y-offset, using a format-expression, where "value" keyword represents the Layer.Value property, so the y-offset of the layer is calculated based on the value. For instance, "(value=0)?0:48", means that if the layer's value is 0, the y-offset is 0, otherwise it is 48 pixels. This flag is useful when you want to link the layer's vertical position to its value, such as in a switch control where the knob's position (y-offset) represents the on/off state (value) of the switch (equivalent of Layer.ValueToOffsetY property)	[v2y=(value=0)?0:48]
   [width]	width of the layer using format-expression, where "width" indicates the control's width in pixels and "height" indicates the control's height in pixels. For instance, "width/4" expression sets the layer's width to a quarter of the control's width (equivalent of Layer.Width property)	[width=width/4]
   [x]	x-offset of layer. The layer's actual x-offset is the sum of left, defaultOffsetX, and offsetX, while the actual y-offset is the sum of top, defaultOffsetY, and offsetY. For instance, if you set the offsetX field to 10, the defaultOffsetX field to 5, the layer is shown with a total x-offset of 15 pixels from the position specified by the left field (equivalent of Layer.OffsetX property)	[x=-32]
   [xCenter]	defines the x-coordinate of the rotation center relative to the layer specified by the Layer.RotateCenterLayer property, using a format expression where "lwidth" or "width" represents the layer's width in pixels and "lheight" or "height" represents its height, so "lwidth/2" places the rotation center at the horizontal middle of the layer (equivalent of Layer.RotateCenterX property)	[xCenter=lwidth/2]
   [xValid]	validates, limits or spans the x-offset value of the layer, using a format-expression, where is supports "x" (x-offset value of the layer), "y" (y-offset value of the layer), "lwidth" (layer's width in pixels), "lheight" (layer's height in pixels), "width" (control's width in pixels), "height" (control's height in pixels) and "value" (can be x- or y-offset) keywords. For instance, if you set the offsetXValid field to "x MIN 0 MAX 48", the offsetX field is validated to be between 0 and 48 pixels, while "round(x/8)*8" expression spans the offsetX value to the closest multiple of 8 pixels (equivalent of Layer.OffsetXValid property)	[xValid=x MIN 0 MAX 48]
   [y]	y-offset of layer. The layer's actual y-offset is the sum of top, defaultOffsetY, and offsetY, while the actual x-offset is the sum of left, defaultOffsetX, and offsetX. For instance, if you set the offsetY field to 10, the defaultOffsetY field to 5, the layer is shown with a total y-offset of 15 pixels from the position specified by the top field (equivalent of Layer.OffsetY property)	[y=-32]
   [yCenter]	definex the y-coordinate of the rotation center relative to the layer specified by the Layer.RotateCenterLayer property, using a format expression where "lwidth" or "width" represents the layer's width in pixels and "lheight" or "height" represents its height, so "lheight/2" places the rotation center at the vertical middle of the layer (equivalent of Layer.RotateCenterY property)	[yCenter=lheight/2]
   [yValid]	validates, limits or spans the y-offset value of the layer, using a format-expression, where is supports "x" (x-offset value of the layer), "y" (y-offset value of the layer), "lwidth" (layer's width in pixels), "lheight" (layer's height in pixels), "width" (control's width in pixels), "height" (control's height in pixels) and "value" (can be x- or y-offset) keywords. For instance, if you set the offsetYValid field to "y MIN 0 MAX 48", the offsetY field is validated to be between 0 and 48 pixels, while "round(y/8)*8" expression spans the offsetY value to the closest multiple of 8 pixels (equivalent of Layer.OffsetYValid property)	[yValid=y MIN 0 MAX 48]

2. object, where each property defines a layer with its options as an object of LayerOptions type. The name of the property is the key of the layer, and the value is an object that defines the layer's options (equivalent of LayerOptions type)
3. array of objects of LayerOptions type, where each object defines a layer with its options (equivalent of LayerOptions type)

The getter of the Layers property returns the layers collection as an object of Layers type, while the setter accepts the layers in any of the above formats.

The following statements are equivalent:

(as string)

 "gauge_back[key=back][yCenter=lheight/2 + 78][grayscale=100-value],gauge_needle[key=needle][avalid=value < 90 ? value : (value < 180 ? 90 : (value < 270 ? 270 : value))][a2v=value >= 270 ? (value - 270)/90*50 : (value/90)*50 + 50][v2a=value < 50 ? (270 + value/50*90) : (value - 50)/50 * 90][drag=rotate][brightness.green=value][contrast.green=value][contrast.blue=0][contrast.red=0]"

(as object):

 {
   "back":
   {
     back: "gauge_back",
     rotateCenterY: "lheight/2 + 78",
     grayscale: "100-value"
   },
   "needle":
   {
     back: "gauge_needle",
     rotateAngleValid: "value < 90 ? value : (value < 180 ? 90 : (value < 270 ? 270 : value))",
     rotateAngleToValue: "value >= 270 ? (value - 270)/90*50 : (value/90)*50 + 50",
     valueToRotateAngle: "value < 50 ? (270 + value/50*90) : (value - 50)/50 * 90",
     onDrag: "rotate",
     brightness: { green: "value" },
     contrast: { green: "value", blue: 0, red: 0 }
   }
 }

(as array):

[
  {
    key: "back",
    back: "gauge_back",
    rotateCenterY: "lheight/2 + 78",
    grayscale: "100-value"
  },
  {
    key: "needle",
    back: "gauge_needle",
    rotateAngleValid: "value < 90 ? value : (value < 180 ? 90 : (value < 270 ? 270 : value))",
    rotateAngleToValue: "value >= 270 ? (value - 270)/90*50 : (value/90)*50 + 50",
    valueToRotateAngle: "value < 50 ? (270 + value/50*90) : (value - 50)/50 * 90",
    onDrag: "rotate",
    brightness: { green: "value" },
    contrast: { green: "value", blue: 0, red: 0 }
  }
]

The Listeners field defines the events of the control, as an object of exontrol.Lts type. The exontrol.Lts type supports forEach(callback, thisArg) method that helps you to enumerate the events the control supports. The on() method adds an event listener to the specified event or defines a keyboard shortcut. The on() method enables you to listen for events and execute custom code when those events occur, or to define keyboard shortcuts that trigger specific actions within the component. You can use the on() method to enhance the interactivity and functionality of your application by responding to user actions or keyboard inputs. Use the off() method to remove previously bound event handlers or keyboard shortcuts. The Events section lists the events the component supports.

The following sample shows how you can get all events the component currently supports:

oGauge.Listeners.forEach(function(name)
{
 console.log(name);
});

The following sample displays information about the layer being clicked:

oGauge.Listeners.Add("onclick", function (oEvent)
{
 console.log(oEvent);
});

or

oGauge.on("click", function (oEvent)
{
 console.log(oEvent);
});

where oGauge is an object of Gauge type

The Locked property indicates whether the control is locked (protected) or unlocked. When locked, all layers are locked, so the user cannot select any layer to drag or modify the control. When unlocked, all layers are unlocked, so the user can select any layer to drag or modify the control. The Locked property is identical to the ReadOnly property, so setting one of them automatically sets the other to the same value. By default, the Locked property is set to false, which means that the control is unlocked and the user can select any layer to drag or modify the control.

false {boolean}, unlocks the control (can select any layer)
true {boolean}, locks the control (can't select any layer)

The Options property defines the options of the control by applying the given options object of Gauge.Options type. The control options are defined by an object of Gauge.Options type, which specifies different options to display the control such as layers, layerAutoSize, layerOfValue, layerDragAny and value. Every option of the Gauge.Options object is mapped to a property of the control, which means that you can also set the options by setting the value of each property. For instance, the layers field of Gauge.Options is mapped to the Layers property of the control, so you can set the layers by setting the value of the Layers property. The Options property is useful when you want to set multiple options at once by providing an object of Gauge.Options type, while setting each property is useful when you want to set specific options.

{debug: true} {object}, sets the debug field to true
{layers: "gauge_back,gauge_needle[key=needle][drag=rotate]"} {object}, sets the layers field to specify two layers

The ReadOnly property defines whether the control is read-only (identical to the Locked property). When set to read-only, the control is locked and the user cannot select any layer to drag or modify the control. When set to not read-only, the control is unlocked and the user can select any layer to drag or modify the control. The ReadOnly property is identical to the Locked property, so setting one of them automatically sets the other to the same value. By default, the ReadOnly property is set to false, which means that the control is unlocked and the user can select any layer to drag or modify the control.

false {boolean}, unlocks the control (can select any layer)
true {boolean}, locks the control (can't select any layer)

The Shortcuts field defines the shortcuts of the control, as an object of exontrol.Sts type. The Shortcuts field defines the shortcuts of the control, as an object of exontrol.Sts type. The on() method enables you to listen for events and execute custom code when those events occur, or to define keyboard shortcuts that trigger specific actions within the component. You can use the on() method to enhance the interactivity and functionality of your application by responding to user actions or keyboard inputs. Use the off() method to remove previously bound event handlers or keyboard shortcuts. In order to provide keyboard support for the component, the owner <canvas> element must include the tabIndex attribute, as <canvas ... tabIndex="0">. You can associated a function or a callback to any shortcut.

The following sample resets the gauge's value once the user presses the Escape key:

oGauge.Shortcuts.Add( "Escape", function(oShortcut)
{
  oGauge.Value && oGauge.Smooth(function()
  {
    oGauge.Value = 0;
  })
});

where oGauge is an object of Gauge type

The ShowLayers property defines the only layers to be shown on the control. The ShowLayers property is useful when you have multiple layers but want to display only some of them based on a specific condition. For instance, you may have a gauge control with multiple layers such as "hour", "minute", and "second" layers, but you want to show just the "hour" and "minute" layers when the seconds are not important. The Layer.Visible property shows or hides the layer.

Specifies the layers to display within the control as explained:

• "all" {string}, specifies that all visible layers are shown (The Layer.Visible property shows or hides the layer)
• "" {string}, no layer is shown in the control (no matter of the Layer.Visible property)
• "n1,n2,n3,..." {string}, specifies the list of layers separated by comma (without spaces) that are shown in the control, where n1, n2, ... can be numbers (the index of the layer) or strings (the key of the layer). For instance, "hour,min,sec" means that the layers with keys "hour", "min", and "sec" are shown in the control, while the other layers are hidden (no matter of the Layer.Visible property)

null {null}, specifies that all visible layers are shown (equivalent of "all")
"" {string}, indicates than no layes is shown
"hour,min,sec" {string}, indicates that the only "hour" "min" and "sec" layers are shown

The Tfi property defines the font attributes for the control's captions, allowing precise customization of their appearance by specifying the text style (such as bold or italic), font family, and font size, either as a string (e.g., "b monospace 16") or as an object (e.g., {bold: true, italic: false, fontName: "monospace", fontSize: 16}), and immediately applies these settings to update the displayed captions.

The value as {string} supports any of the following keywords (each keyword can be specified using first letters only such as "b" for "bold) separated by space characters:

• bold, displays the text in bold (equivalent of <b> tag)
• italic, displays the text in italics (equivalent of <i> tag)
• underline, underlines the text (equivalent of <u> tag)
• strikeout, specifies whether the text is strike-through (equivalent of <s> tag)
• <fontName name>, specifies the font's family (equivalent of <font name> tag)
• <fontSize size>, specifies the size of the font (equivalent of <font ;size> tag)
• <fgColor CSSColor>, specifies the text's foreground color (equivalent of <fgcolor> tag)
• <bgColor CSSColor>, specifies the text's background color (equivalent of <bgcolor> tag)
• <shaColor CSSColor;width;offset>, defines the text's shadow (equivalent of <sha color;width;offset> tag)
• <outColor CSSColor>, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
• <graColor CSSColor;mode;blend>, defines a gradient text (equivalent of <gra color;mode;blend> tag)

Any other word within the string value that's not recognized as a keyword is interpreted as:

• name of the font (not a number), specifies the font's family (equivalent of <font name> tag)
• size of the font (number), specifies the size of the font (equivalent of <font ;size> tag)

The value as {object} supports any of the following fields:

• bold {boolean}, displays the text in bold (equivalent of <b> tag)
• italic {boolean}, displays the text in italics (equivalent of <i> tag)
• underline {boolean}, underlines the text (equivalent of <u> tag)
• strikeout {boolean}, specifies whether the text is strike-through (equivalent of <s> tag)
• fontName {string}, specifies the font's family (equivalent of <font name> tag)
• fontSize {number}, specifies the size of the font (equivalent of <font ;size> tag)
• fgColor {string}, specifies the text's foreground color (CSScolor) (equivalent of <fgcolor> tag)
• bgColor {string}, specifies the text's background color (CSScolor) (equivalent of <bgcolor> tag)
• shaColor {object}, specifies an object of {color, width, offset} type that defines the text's shadow (equivalent of <sha color;width;offset> tag), where:
  • color {string}, defines the color of the text's shadow (CSScolor)
  • width {number}, defines the size of the text's shadow
  • offset {number}, defines the offset to show the text's shadow relative to the text
• outColor {string}, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
• graColor {object}, specifies an object of {color, mode, blend} type that defines a gradient text (equivalent of <gra color;mode;blend> tag), where:
  • color {string}, defines the gradient-color (CSScolor)
  • mode {number}, defines the gradient direction as 0 (left-right), 1 (default, top-bottom), 2 (left-center-right), and 3 (top-center-bottom)
  • blend {number}, defines the gradient blend as a value between 0 and 1

CSSColor or CSS legal color values can be specified by the following methods:

• Hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF. For example, #0000ff value is rendered as blue, because the blue component is set to its highest value (ff) and the others are set to 00.
• Hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF. For example, #0000ff80 defines a semi-transparent blue.
• RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255. For example, rgb(0,0,255) defines the blue color.
• RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, rgba(0,0,255,0.5) defines a semi-transparent blue.
• HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors. For example, hsl(240, 100%, 50%) defines the blue color.
• HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, hsla(240, 100%, 50%,0.5) defines a semi-transparent blue.
• Predefined/Cross-browser color names, 140 color names are predefined in the HTML and CSS color specification. For example, blue defines the blue color.

null {null}, the tfi field is ignored
"bold monospace 16 <fg blue>" {string}, defines Monospace font of 16px height, bold and blue
{bold: true, fontName: "monospace", fontSize: 16, fgColor: "blue"} {object}, defines Monospace font of 16px height, bold and blue

The Value property defines the control's current value. The LayerOfValue property specifies the index or key of the layer whose value determines the control's value. Since each layer can have its own value (for example, a rotation angle or an offset), LayerOfValue identifies which layer is used as the source of the control's value. The Layer.Value property defines the value of a layer. This value can represent different things depending on how the layer is configured, such as a position offset or a rotation angle.

This value can be converted into other representations using "mapping" properties:

• Layer.ValueToRotateAngle property converts the layer's value to a rotation angle, which is useful when the layer's value represents a rotation and you want to specify how that value maps to an actual angle of rotation.
• ValueToOffsetX and ValueToOffsetY properties of the Layer object convert the layer's value to positional offsets (x and y), which is useful when the layer's value represents a position and you want to specify how that value maps to actual pixel offsets on the control.

In the opposite direction:

• Layer.RotateAngleToValue property converts a rotation angle back into the layer's value, which is useful when the layer is rotated (for example, by user interaction) and you want to update the layer's value based on its new rotation angle.
• Layer.OffsetToValue property converts positional offsets back into the layer's value, which is useful when the layer is moved (for example, by user interaction) and you want to update the layer's value based on its new position.

Therefore, the control's value is ultimately derived from the Layer.Value of the layer specified by layerOfValue, and its meaning depends on how that layer interprets and maps its value. The onchange event occurs when the control's value is changed.

0 {number}, sets the control's value to 0
(new Date() - Date.Today())/1000/24/60/60 {number}, sets the control's value to current-time as a number between 0 and 1.

The WheelChange property defines the amount the calendar scrolls when the user rolls the mouse wheel. This setting allows you to adjust the sensitivity of the mouse wheel interaction with the control.

• Setting wheelChange to 0 disables mouse wheel actions, preventing the control from changing when the wheel is scrolled
• Setting wheelChange to a positive number, such as 5, increases the control's value by that amount each time the wheel is rotated, enabling faster adjustments

By modifying this value, you can fine-tune the control's responsiveness, making it easier for users to perform precise changes or larger adjustments as needed.

0 {number}, locks any action the mouse's wheel performs
5 {number}, increases the control's value by 5 once the user rotates the mouse wheel

The BeginUpdate() method suspends the control's render until the EndUpdate() method is called. It maintains performance, while multiple changes occurs within the control. The BeginUpdate() method is mostly used when you want to perform multiple changes to the control without refreshing the control after each change, and once all changes are performed, you can call the EndUpdate() method to refresh the control. You can use the Update() method to perform multiple changes at once. The Smooth() method makes the control transition smoothly from the current layout to a new layout. In short, it applies a gradual, animated change to the layout generated by the callback, instead of switching instantly. The BeginUpdate/EndUpdate() methods are not required to be called when you use the Update() or Smooth() methods, because the methods already maintain performance while performing multiple changes to the control.

oGauge.BeginUpdate();
  // performs multiple changes to the control
oGauge.EndUpdate();

The EndUpdate() method resumes the control's render, after it is suspended by the BeginUpdate() method. The EndUpdate() method is mostly used after calling the BeginUpdate() method, to refresh the control after performing multiple changes to the control. You can use the Update() method to perform multiple changes at once. The Smooth() method makes the control transition smoothly from the current layout to a new layout. In short, it applies a gradual, animated change to the layout generated by the callback, instead of switching instantly. BeginUpdate/EndUpdate() methods are not required to be called when you use the Update() or Smooth() methods, because the methods already maintain performance while performing multiple changes to the control.

oGauge.BeginUpdate();
 // performs multiple changes to the control
oGauge.EndUpdate();

The GetCanvas() method returns the HTMLCanvasElement object where the control is currently running on. The control is always running on a canvas, which is the canvas of the control's canvas-window (exontrol.CW). The GetCanvas() method is useful when you need to access the canvas directly. You can also use the GetCanvas() method to retrieve the canvas's context and perform custom drawing operations using the Canvas API. It is recommended to call the exontrol.CC.Resize(<canvas>, [width], [height]) method to resize and refresh the control; otherwise, the control's content is lost.

The GetSmooth() method gets the time, in milliseconds, the control takes to transition from one layout to another. Setting the Smooth property to 0 means that no smooth transitions are performed when the control changes from one layout to another. Setting the Smooth property to 125 means that a smooth transition is performed over 125 milliseconds. The Smooth() method smoothly transitions the control from the current layout to a new layout, applying gradual changes rather than an immediate switch.

0 {number}, no smooth changes once the control goes from a layout to another
125 {number}, specifies that a smooth-transition is performed from a layout to another for 125 ms.

The Layer() method returns the layer associated with the given index or key. Each layer of the control has an index and optionally a key. The Layer method is equivalent with the Layers.Item() method. The index of the layer is determined by the order of the layers in the control, starting from 0 for the bottom-most layer. The key of the layer is a string that can be assigned to the layer using the Layer.Key property. The Layer() method allows you to access a specific layer by its index or key, and returns an object of Layer type that represents that layer. Once you have the Layer object, you can access its properties and methods to manipulate that layer, such as changing its value, position, rotation, visibility, etc.

The following statements are equivalent:

 oGauge.Layer(0) {Layer}, returns the layer with index 0
 oGauge.Layers.Item(0) {Layer}, returns the layer with index 0

where oGauge is an instance of Gauge control

The Refresh() method forces the control to redraw and update its layout without modifying any of its properties or data. It is typically used when the visual appearance needs to be recalculated or repainted, even though no structural or state changes were made.

For example, call Refresh() when:

• The control's container has been resized and the layout must be recalculated.
• External CSS or styling changes affect the control's appearance.
• The control becomes visible after being hidden.
• You need to ensure the UI is visually synchronized with its current internal state.

The method does not alter the control's data, options, or configuration - it only updates the rendered output.

oGauge.Refresh(), refreshes the control

The SetClientRect() method defines a client area for the control. The control is drawn within the client area, which is defined by an array of [x,y,width,height] type. The SetClientRect() method is useful when you want to specify a specific area within the canvas where the control should be drawn, instead of using the entire canvas as the client area. By defining a client area, you can have multiple controls running on the same canvas without overlapping each other, as each control can have its own client area. The SetClientRect() method also allows you to change the client area dynamically, for example, in response to user interactions or window resizing.

The SetSmooth() method sets the time, in milliseconds, the control takes to transition from one layout to another. Setting the Smooth property to 0 means that no smooth transitions are performed when the control changes from one layout to another. Setting the Smooth property to 125 means that a smooth transition is performed over 125 milliseconds. The Smooth() method smoothly transitions the control from the current layout to a new layout, applying gradual changes rather than an immediate switch.

0 {number}, no smooth changes once the control goes from a layout to another
125 {number}, specifies that a smooth-transition is performed from a layout to another for 125 ms.

The Shuffle() method arranges randomly all layers within the control (the Refresh() method always resets any previous shuffle). The Shuffle() method is useful to create a random layout of the control's layers, which can be used for decorative purposes or to create a "shuffle" effect. The Shuffle() method randomly changes the positions of the layers based on the specified ratio. The ratio parameter controls how much the layers are randomized relative to their current layout. For example, a ratio of 0 means that the layers are not moved or shuffled at all, while a ratio of 1 means that the layers can be randomized up to their full width and height. You can use any value between 0 and 1 to achieve different levels of randomness in the layout of the layers.

0 {number}, specifies that the layers are not moved/shuffled at all (the layout is restored)
0.5 {number}, specifies that the layers are randomized up to half of the control's width and height from their current positions
1 {number}, specifies that the layers are randomized up to the control's full width and height from their current positions

The Smooth() method makes the control transition smoothly from the current layout to a new layout. In short, it applies a gradual, animated change to the layout generated by the callback instead of switching instantly. The smooth transition goes from the current layout to the new layout generated by the callback. The smooth field defines the time, in milliseconds, the control takes to transition from one layout to another. The BeginUpdate() and EndUpdate() methods are not required when using the Update() or Smooth() methods, as these methods already handle performance while performing multiple changes to the control.

The Smooth() method performs smooth changes for change of any of the following properties for any layer, while it is called during the Smooth's callback:

• Value {number}, sets the layer's value
• DefaultOffsetX {number}, sets a value that indicates the default x-offset of the layer.
• DefaultOffsetY {number}, sets a value that indicates the default y-offset of the layer.
• OffsetX {number}, sets a value that indicates the x-offset of the layer.
• OffsetY {number}, sets a value that indicates the y-offset of the layer.
• DefaultRotateAngle {number}, specifies the default angle to rotate the layer (degree)
• RotateAngle {number}, specifies the angle to rotate the layer (degree)

Shorty, the Smooth() method records the changes of the control (offset or rotation-angle for any layer) during the Smooth's callback, and performs smooth changes for properties being changed only, instead of switching instantly to the new layout generated by the callback.

The following sample increases the control's value by 5 with a smooth-transition:

 oGauge.Smooth(function()
 {
   this.Value += 5;
 });

The following sample changes the default y-offset of the first layer to 64 with a smooth-transition:

 oGauge.Smooth(function()
 {
  oGauge.Layer(0).DefaultOffsetY = 64
 })

The Unshuffle() method restores the layers of the control to their original layout (the layout before any shuffle). The Unshuffle() method is useful to restore the original layout of the control's layers after they have been randomly arranged using the Shuffle() method. When you call the Unshuffle() method, it resets the positions of all layers to their original layout, which is the layout defined by their initial configuration or by the last Refresh() method call. The Unshuffle() method is essentially a shortcut for calling Shuffle(0), which indicates that no randomization should be applied and the layers should be returned to their original positions.

oGauge.Unshuffle(), restores the layers of the control to their original layout (the layout before any shuffle)

The Update() method locks the control's paint during the callback, and invalidates the control once the method ends. The BeginUpdate/EndUpdate() methods are not required to be called when you use the Update() or Smooth() methods, because the methods already maintain performance while performing multiple changes to the control. The BeginUpdate/EndUpdate() methods are not required to be called when you use the Update() or Smooth() methods, because the methods already maintain performance while performing multiple changes to the control.

oGauge.Update(function()
{
 // performs multiple changes to the control
});

The off() method removes a previously bound handler from a specified event, allowing you to stop listening for that event and prevent the associated actions from being executed. Also removes keyboard shortcuts previously defined using the on() method. The event name is case-insensitive and may or may not include the 'on' prefix. For example, 'click' is equivalent to 'onclick' and vice versa. If the event parameter is missing/empty/undefined, all event handlers are removed from the control. If the listener parameter is missing/empty/undefined, all handlers of the specified event are removed. If the method parameter is missing/empty/undefined, the listener[type]() function is used to compare and remove the handler(s).

The following example removes the click event handler from the control:

oGauge.off("click");

where oGauge is an object of Gauge type.

This sample is equivalent to:

oGauge.Listeners.Remove("onclick");

The following example removes all event handlers from the control:

oGauge.off();

where oGauge is an object of Gauge type.

This sample is equivalent to:

oGauge.Listeners.Clear();

or

oGauge.Listeners.Remove();

The on() method adds an event listener to the specified event or defines a keyboard shortcut. The on() method enables you to listen for events and execute custom code when those events occur, or to define keyboard shortcuts that trigger specific actions within the component. You can use the on() method to enhance the interactivity and functionality of your application by responding to user actions or keyboard inputs. Use the off() method to remove previously bound event handlers or keyboard shortcuts.

The following example logs event details when the control is clicked:

oGauge.on("click", function(oEvent)
{
  console.log(oEvent);
});

where oGauge is an object of Gauge type.

This sample is quivalent of 

oGauge.Listeners.Add("onclick", function (oEvent)
{
  console.log(oEvent);
});

The onanchorclick event occurs once the user clicks an anchor element (the <a id;options> ex-HTML part marks an anchor or hyperlink element). The onclick event occurs once the user clicks a selectable layer. The Layer.Fore property defines the ex-HTML content of the layer. For instance, "`<a back>` + value" defines an anchor element with "back" identifier and no options.

The following samples display information about the element being clicked:

 oGauge.Listeners.Add("onanchorclick", function (oEvent)
 {
  console.log(oEvent);
 })

or

 oGauge.on("anchorclick", function (oEvent)
 {
  console.log(oEvent);
 })

The onchange event occurs when the control's value is changed. The Gauge.Value property indicates the control's value, while Layer.Value property defines the layer's value. The LayerOfValue property indicates the layer that defines the control's value, so when that layer's value is changed, the control's value is changed as well, and the onchange event occurs. The Layer.OnDrag property specifies the drag behavior of the layer.

The onchange event may occur if any of the following properties are changed:

• Layer.Value property of the layer specified by LayerOfValue property, which defines the control's value
• Layer.OffsetX property of any layer, which defines the horizontal offset of the layer from its default position
• Layer.OffsetY property of any layer, which defines the vertical offset of the layer from its default position
• Layer.RotateAngle property of any layer, which defines the rotation angle of the layer from its default angle

The following samples display the layer whose value is changed:

oGauge.onchange = function (oEvent)
{
 console.log(oEvent);
}

or

oGauge.Listeners.Add("onchange", function (oEvent)
{
 console.log(oEvent);
})

or

oGauge.on("change", function (oEvent)
{
 console.log(oEvent);
})

where oGauge is an object of Gauge type

The onclick event occurs once the user clicks a selectable layer. The Layer.Selectable property specifies whether a layer is selectable, so the onclick event occurs only if the user clicks a selectable layer. The onanchorclick event occurs once the user clicks an anchor element (the <a id;options> ex-HTML part marks an anchor or hyperlink element), so if the user clicks an anchor element. You can always the canvas's "click" event to get the click information, but the onclick event provides more specific information about the click on the layer. The Layer.OnDrag property specifies the drag behavior of the layer, so if the user clicks a layer with a drag behavior, the onclick event occurs once the user clicks the layer, and the ondragstart event occurs once the user starts dragging the layer.

The following samples display information once the user clicks a layer:

 oGauge.onclick = function (oEvent)
 {
  console.log(oEvent);
 }

or

 oGauge.Listeners.Add("onclick", function (oEvent)
 {
  console.log(oEvent);
 })

or

 oGauge.on("click", function (oEvent)
 {
  console.log(oEvent);
 })

where oGauge is an object of Gauge type

The ondrag event occurs once the user drags the layer to a new position. The ondragstart event notifies that the user starts draggging the layer. The ondragend event notifies that dragging the layer ends. The onclick event occurs once the user clicks a selectable layer, so if the user clicks a layer with a drag behavior, the onclick event occurs once the user clicks the layer, and the ondragstart event occurs once the user clicks the layer. The Layer.OnDrag property specifies the drag behavior of the layer, so if the user clicks a layer with a drag behavior, the onclick event occurs once the user clicks the layer, and the ondragstart event occurs once the user starts dragging the layer.

The following samples display information while draging (move, rotate or swipe) the layer:

 oGauge.ondrag = function (oEvent)
 {
  console.log(oEvent);
 }

or

 oGauge.Listeners.Add("ondrag", function (oEvent)
 {
  console.log(oEvent);
 })

or

 oGauge.on("drag", function (oEvent)
 {
  console.log(oEvent);
 })

where oGauge is an object of Gauge type

The ondragend event notifies that dragging the layer ends. The ondragstart event notifies that the user starts draggging the layer. The onclick event occurs once the user clicks a selectable layer, so if the user clicks a layer with a drag behavior, the onclick event occurs once the user clicks the layer, and the ondragstart event occurs once the user clicks the layer. The ondrag event occurs once the user drags the layer to a new position. The Layer.OnDrag property specifies the drag behavior of the layer, so if the user clicks a layer with a drag behavior, the onclick event occurs once the user clicks the layer, and the ondragstart event occurs once the user starts dragging the layer.

The following samples display information while the user ends draging (move, rotate or swipe) a layer:

 oGauge.ondragend = function (oEvent)
 {
  console.log(oEvent);
 }

or

 oGauge.Listeners.Add("ondragend", function (oEvent)
 {
  console.log(oEvent);
 })

or

 oGauge.on("dragend", function (oEvent)
 {
  console.log(oEvent);
 })

where oGauge is an object of Gauge type

The ondragstart event notifies that the user starts draggging the layer. The ondragend event notifies that dragging the layer ends. The onclick event occurs once the user clicks a selectable layer, so if the user clicks a layer with a drag behavior, the onclick event occurs once the user clicks the layer, and the ondragstart event occurs once the user clicks the layer. The ondrag event occurs once the user drags the layer to a new position. The Layer.OnDrag property specifies the drag behavior of the layer, so if the user clicks a layer with a drag behavior, the onclick event occurs once the user clicks the layer, and the ondragstart event occurs once the user starts dragging the layer.

The following samples display information once the user starts draging (move, rotate or swipe) a layer:

 oGauge.ondragstart = function (oEvent)
 {
  console.log(oEvent);
 }

or

 oGauge.Listeners.Add("ondragstart", function (oEvent)
 {
  console.log(oEvent);
 })

or

 oGauge.on("dragstart", function (oEvent)
 {
  console.log(oEvent);
 })
 
where oGauge is an object of Gauge type

The onlayerin event notifies that the cursor enters the layer. The onlayerin event can be used to perform actions when the cursor enters a specific layer, such as displaying additional information, changing the appearance of the layer, or triggering other interactive behaviors. The onlayerout event can be used in conjunction with the onlayerin event to perform actions when the cursor leaves the layer, allowing for a more dynamic and responsive user experience.

The following samples display the layer the cursor enters in:

 oGauge.onlayerin = function (oEvent)
 {
  console.log(oEvent);
 }

or

 oGauge.Listeners.Add("onlayerin", function (oEvent)
 {
  console.log(oEvent);
 })

or

 oGauge.on("layerin", function (oEvent)
 {
  console.log(oEvent);
 })

where oGauge is an object of Gauge type

The onlayerout event notifies that the cursor exits the layer. The onlayerout event can be used to perform actions when the cursor leaves a specific layer, such as hiding additional information, reverting the appearance of the layer, or triggering other interactive behaviors. The onlayerin event can be used in conjunction with the onlayerout event to perform actions when the cursor enters the layer, allowing for a more dynamic and responsive user experience.

The following samples display the layer once the cursor leaves it:

 oGauge.onlayerout = function (oEvent)
 {
  console.log(oEvent);
 }

or

 oGauge.Listeners.Add("onlayerout", function (oEvent)
 {
  console.log(oEvent);
 })

or

 oGauge.on("layerout", function (oEvent)
 {
  console.log(oEvent);
 })

where oGauge is an object of Gauge type