new Gauge(client, oOptsopt)
The ExGauge/JS library provides graphics capabilities to visually display and edit the amount, level, or contents of something. The view can show one or more layers, where each layer can display one or more transparent pictures, HTML captions which can be clipped, moved, rotated or combination of them, by dragging the mouse, rolling the mouse wheel, or using the keyboard. The ExGauge/JS is a HTML standalone-component, written in JavaScript, that uses no third-party libraries.
Every option of the Gauge.Options type has associated a property of the control. For instance, the option:
cursors {string}, specifies the mouse cursor to be displayed when pointing over a part of the controlis associated with the property:
Cursors {string}, specifies the mouse cursor to be displayed when pointing over a part of the controlwhich means that the following statements are equivalent:
oGauge.Options = {cursors: "crosshair(dable)"}where oGauge is an object of Gauge type
oGauge.SetOptions({cursors: "crosshair(dable)"})
oGauge.Cursors = "crosshair(dable)"
oGauge.SetCursors("crosshair(dable)")
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
client |
any | The client parameter indicates the control's client area as:
|
|
oOpts |
object |
<optional> |
An object of Gauge.Options type that defines different options to display the control. |
Requires:
- module:exontrol.commmon.min.js
Requires
- module:exontrol.commmon.min.js
Classes
Members
(static, readonly) OnDragLayerEnum :number
Specifies the operation a layer is performed once the user drags it.
Type:
- number
Properties:
| Name | value | Type | Description |
|---|---|---|---|
exDoNothing |
0 |
number | Nothing happens if the user drags the layer. |
exDoMove |
1 |
number | The layer is moved while dragging. The layer's OffsetX and OffsetY indicates the current (x,y) position of the layer. |
exDoRotate |
2 |
number | The layer is rotated while dragging. The RotateAngle property indicates the currently rotation angle. |
exDoRotamove |
3 |
number | The layer is moved by rotation while dragging. The RotateAngle property indicates the currently rotation angle. In this case, the layer's RotamoveOffsetX / RotamoveOffsetY property indicates the current (x,y) position of the layer. |
(static, readonly) ViewableLObjEnum :number
Indicates the type of layers the control supports (visible/selectable).
Type:
- number
Properties:
| Name | value | Type | Description |
|---|---|---|---|
exVisible |
1 |
number | Defines a visible layer |
exSelectable |
2 |
number | Defines a selectable layer |
(static, readonly) type :string
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"
Type:
- string
- Since:
- 1.8
Example
console.log(exontrol.Gauge.type); // logs "Gauge"(static, readonly) version :string
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.2
Type:
- string
Example
console.log(exontrol.Gauge.version); // displays the version of the control, for instance "5.2"(static) states :string
The states field defines the list of properties (separated by comma) to save or restore using the State object.
Type:
- string
- Since:
- 2.2
(static) vAlpha :number
The vAlpha field specifies a value between 0 and 255 that defines pixels visible within the alpha chanel (any pixel of RGBA format with A(lpha) >= vAlpha is considered being visible).
Type:
- number
- Since:
- 2.2
Listeners :exontrol.Lts
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.
Type:
- exontrol.Lts
Example
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 typeShortcuts :exontrol.Sts
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.
Type:
- exontrol.Sts
Example
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 typeMethods
BeginUpdate()
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 performs a smooth-transition from a layout to another. 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.
Example
oGauge.BeginUpdate();
// performs multiple changes to the control
oGauge.EndUpdate();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 performs a smooth-transition from a layout to another. 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.
Example
oGauge.BeginUpdate();
// performs multiple changes to the control
oGauge.EndUpdate();GetCanvas() → {HTMLCanvasElement}
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.
Returns:
Returns the HTMLCanvasElement object the control is running on.
- Type
- HTMLCanvasElement
GetCanvasRect() → {array}
The GetCanvasRect() method returns the canvas's client rectangle.
Returns:
Returns an array of [x,y,width,height] type that specifies the canvas's client rectangle
- Type
- array
GetClientRect() → {array}
The GetClientRect() method returns the control's client area.
Returns:
Returns an array of [x,y,width,height] type that specifies the control's client area
- Type
- array
GetCursors() → {string}
The GetCursors() method retrieves the mouse cursors assigned to different parts of the control. These cursors determine the pointer appearance when the user hovers over specific areas, allowing you to provide visual feedback for interactive regions of the control.
Returns:
A string expression that defines the mouse cursor to display when pointing over different parts 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 "part" 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
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
- Type
- string
GetDebug() → {boolean}
The GetDebug() method specifies whether the control shows the layers in debug mode.
Returns:
Returns true, if the control shows the layers in debug mode
- Type
- boolean
GetFormatText() → {exontrol.DrawTextFormatEnum}
The GetFormatText() method specifies the format to display the layer's caption.
- Since:
- 1.1
Returns:
Returns a value of exontrol.DrawTextFormatEnum type, that defines the format to display the layer's caption.
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.
- Type
- exontrol.DrawTextFormatEnum
GetLayerAutoSize() → {number|string}
The GetLayerAutoSize() method specifies the index or the key of the layer that determines the size to display all layers.
Returns:
Returns the index or the key of the layer that determines the size to display all layers.
- Type
- number | string
GetLayerDragAny() → {number|string}
The GetLayerDragAny() method specifies the layer to drag (rotate, move or sweep) once the user clicks anywhere on the control.
Returns:
Returns the index or the key of the layer to drag (rotate, move or sweep) once the user clicks anywhere on the control.
- Type
- number | string
GetLayerOfValue() → {number|string}
The GetLayerOfValue() method specifies the index or the key of the layer whose value determines the control's Value property.
Returns:
Returns the index or the key of the layer whose value determines the control's Value property.
- Type
- number | string
GetLayers() → {Layers}
The GetLayers() method gets the control's layers.
Returns:
Returns the control's layers collection.
- Type
- Layers
GetLayersClientRect() → {array}
The GetLayersClientRect() method returns the layers's client area (control's client area).
Returns:
Returns an array of [x,y,width,height] type that specifies the layers's client area
- Type
- array
GetLocked() → {boolean}
The GetLocked() method specifies whether the control is locked(protected) or unlocked.
Returns:
Returns true, if the control is locked(protected) or unlocked
- Type
- boolean
GetOptions() → {Gauge.Options}
The GetOptions() method returns the current options of the control.
Returns:
An object of Gauge.Options that indicates the options to display the control.
- Type
- Gauge.Options
GetReadOnly() → {boolean}
The GetReadOnly() method specifies whether the control is read-only.
- Since:
- 1.8
Returns:
Returns true, if the control is read-only
- Type
- boolean
GetShowLayers() → {string}
The GetShowLayers() method indicates the only layers to be shown.
Returns:
Returns the layers being shown within the control.
Specifies the layers to display within the control as explained:
- "all" {string}, specifies that all visible layers are shown. The Visible property (of exontrol.Gauge.Layer) shows or hides the layer
- "" {string}, no layer is shown in the control, no matter of the layer's Visible property
- "n1,n2,n3,..." {string}, specifies the list of layers to be shown, no matter of the layer's Visible property, where n1, n2, ... are numbers ( indicating the index of the layer to be shown ) or the layer's key. For instance "0" specifies that just the layer with the index 0 is show, "0,1,4", indicates that just layers with the specified index are displayed.
- Type
- string
GetSmooth() → {number}
The GetSmooth() method defines the time in ms the control goes from one layout to another.
Returns:
Returns the time in ms the control goes from one layout to another.
- Type
- number
GetTfi() → {string|object}
The GetTfi() method gets the font attributes to apply on captions of the control. The GetTfi() method returns the font attributes as a string representation such as "b monospace 16" or as an object such as {bold: true, fontName: "monospace", fontSize: 16}. Correspondingly, the Tfi property defines the font attributes that are applied to the control's captions and can be set to customize their appearance.
Returns:
Returns the font attributes as a string representation such as "b monospace 16" or as an object such as {bold: true, fontName: "monospace", fontSize: 16}.
The result as a {string} can include any of the following keywords 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 result 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 result as {object} can include 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.
- Type
- string | object
Example
The following statements are equivalent:
oGauge.GetTfi() {string}, returns the control's font attributes as a string such as "b monospace 16"
oGauge.Tfi {string}, returns the control's font attributes as a string such as "b monospace 16"
where oGauge is an instance of Gauge controlGetValue() → {number}
The GetValue() method specifies the control's value.
Returns:
Returns the control's value.
- Type
- number
GetViewRect() → {array}
The GetViewRect() method returns the position of the owner canvas element within the document.
Returns:
Returns an array of [x,y,width,height] that specifies the position canvas element within the document.
- Type
- array
GetVisibleRect() → {array}
The GetVisibleRect() method indicates the control's visible rectangle.
Returns:
Returns an array of [x,y,width,height] type that specifies the canvas's client rectangle
- Type
- array
GetWheelChange() → {number}
The GetWheelChange() method 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.
Returns:
Returns the amount the control scrolls when the user rolls the mouse wheel.
- Type
- number
Example
The following statements are equivalent:
oGauge.GetWheelChange() {number}, returns the amount the control scrolls when the user rolls the mouse wheel
oGauge.WheelChange {number}, returns the amount the control scrolls when the user rolls the mouse wheel
where oGauge is an instance of Gauge controlLayer(key) → {Layer}
The Layer() method returns a Layer object giving its index or key.
Parameters:
| Name | Type | Description |
|---|---|---|
key |
any | Specifies an integer expression that indicates the index of the layer to be requested, or any other value that indicates the key of the layer (layer's key or back). |
- Since:
- 1.1
Returns:
Returns an object of Layer type associated with the giving index/key
- Type
- Layer
Refresh()
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.
Example
oGauge.Refresh(), refreshes the controlSetCanvas(canvas, localCanvas)
The SetCanvas() method changes the control's canvas where it runs.
Parameters:
| Name | Type | Description |
|---|---|---|
canvas |
any | A string that indicates the indetifier of the element within the document, or a HTMLCanvasElement reference. |
localCanvas |
boolean | Specifies whether the canvas is used localy without requesting the canvas to handle the control itself. |
SetClientRect(client)
The SetClientRect() method defines a client area for the control.
Parameters:
| Name | Type | Description |
|---|---|---|
client |
any | The client parameter indicates the control's client area as:
|
SetCursors(value)
The SetCursors() method assigns or changes the mouse cursors for different parts of the control. These cursors determine the pointer appearance when the user hovers over specific areas, allowing you to provide visual feedback and enhance interactivity for each part of the control.
Parameters:
| Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
value |
string | A string expression that defines the mouse cursor to display when pointing over different parts of the control.
The format of the property is: "cursor(part),cursor(part),..."where:
The "part" can be any of the following:
|
Example
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) layersSetDebug(value)
The SetDebug() method shows the control in debug-mode.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
boolean | A boolean value that indicates whether the control shows the layers in debug mode. |
Example
false {boolean}, shows the layers in normal-mode
true {boolean}, shows the layers in debug-modeSetFormatText(value)
The SetFormatText() method changes the format to display the layer's caption.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
exontrol.DrawTextFormatEnum | Specifies a value of exontrol.DrawTextFormatEnum value that defines the format to show the layer's caption.
A combination of one or more exontrol.DrawTextFormatEnum flags that defines the format to show the layer's caption.
The exontrol.DrawTextFormatEnum type support the following flags:
|
- Since:
- 1.1
Example
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-alignedSetLayerAutoSize(value)
The SetLayerAutoSize() method resizes all layers relative to the giving layer.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
number | string | Specifies the index or the key of the layer that determines the size to display all layers. |
Example
-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)
"items" {string}, specifies that all layers are resized and scaled based on image/picture of the layer with the key "items"SetLayerDragAny(value)
The SetLayerDragAny() method sets the layer to drag (rotate, move or sweep) once the user clicks anywhere on the control.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
number | string | Specifies the index or the key of the layer to drag (rotate, move or sweep) once the user clicks anywhere on the control. |
Example
-1 {number}, specifies that layerDragAny has no effect
0 {number}, specifies that the layer with the index 0 is dragged, once the user clicks anywhere on the control.
"needle" {string}, specifies that the layer with the key "needle" is dragged, once the user clicks anywhere on the control.SetLayerOfValue(value)
The SetLayerOfValue() method changes the layer that determines the control's Value property.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
number | string | Specifies the index or the key of the layer whose value determines the control's Value property. |
Example
-1 {number}, indicates that the control's Value is determined by the last visible layer with [drag] (OnDrag/GetOnDrag()/SetOnDrag(value) methods of exontrol.Gauge.Layer) defined. Shortly, the last visible and dragable layer determines the control's Value.
0 {number}, specifies that the layer with the index 0, defines the control's Value property.
"hour" {string}, specifies that the layer with the key "hour", defines the control's Value property.SetLayers(value) → {Layers}
The SetLayers() method defines the control's layers from a string representation (see layers within the Gauge.Options for more details).
Parameters:
| Name | Type | Description |
|---|---|---|
value |
string | A value that indicates the string representation to get layers from
The layers field defines the control's layers from a string-representation in the following format:
"back[flag=value]...[flag=value],...,back[flag=value]...[flag=value],..."where:
|
Returns:
Returns the control's layers collection
- Type
- Layers
Example
"gauge_back[key=back],gauge_needle[key=needle][drag=rotate]" {string}, defines a gauge control where "gauge_needle" is rotable
"red[drag=rotate],rgba(0,255,0,0.75)[key=green][clip=ellipse][width=width/2][height=height/2][left=width/4][top=height/4][drag=move]" {string}, builds a control using two layers red and 75% green (clipped to an ellispe, which can be moved)SetLocked(value)
The SetLocked() method locks or unlocks the control.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
boolean | A boolean value that indicates whether the control is locked(protected) or unlocked. |
Example
false {boolean}, unlocks the control (can select any layer)
true {boolean}, locks the control (can't select any layer)SetOptions(nOptions, bIncludeAll) → {boolean}
The SetOptions() method applies new options to the Gauge element.
Parameters:
| Name | Type | Description |
|---|---|---|
nOptions |
object | Specifies an object of Gauge.Options type that indicates the new options to apply. |
bIncludeAll |
boolean | Indicates whether all fields of nOptions are included in the element's oOpts object. |
Returns:
Returns true, if there were options applied to the element
- Type
- boolean
SetReadOnly(value)
The SetReadOnly() method sets the control read-only.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
boolean | A boolean value that indicates whether the control is read-only. |
- Since:
- 1.8
Example
false {boolean}, unlocks the control (can select any layer)
true {boolean}, locks the control (can't select any layer)SetShowLayers(value)
The SetShowLayers() method the only layers to be shown within the control.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
string | A String expression that could be:
|
Example
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 control shows just the "hour","min" and "sec" layers only.SetSmooth(value)
The SetSmooth() method changes the time in ms the control goes from one layout to another (0 indicates no smooth-transition is performed).
Parameters:
| Name | Type | Description |
|---|---|---|
value |
number | Indicates the time in ms the control goes from one layout to another. |
Example
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.SetTfi(value)
The SetTfi() method sets 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.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
string | object | Indicates a string representation such as "b monospace 16" or as an object such as {bold: true, fontName: "monospace", fontSize: 16}.
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:
Any other word within the string value that's not recognized as a keyword is interpreted as:
The value as {object} supports any of the following fields:
CSSColor or CSS legal color values can be specified by the following methods:
|
Example
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 blueSetValue(value) → {number}
The SetValue() method changes the layer that determines the control's Value property.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
number | Specifies the index or the key of the layer whose value determines the control's Value property. |
Returns:
Returns the control's value
- Type
- number
Example
0 {number}, change the control's Value to 0, so it could be a zero-offset or a zero-rotation angle, depending on how the layer interprets the value
(new Date() - Date.Today())/1000/24/60/60 {number}, sets the control's value to current-time as a number between 0 and 1.SetWheelChange(value)
The SetWheelChange() method changes 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.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
number | A value that specifies the amount the control scrolls when the user rolls the mouse wheel. |
Example
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 wheelShuffle(ratio)
The Shuffle() method arranges randomly all layers within the control.
Parameters:
| Name | Type | Description |
|---|---|---|
ratio |
number | specifies how far each element is randomized relative to the current size of the layout. For instance, 0 indicates that the element is not moved/shuffled, while 1, indicates that the element can randomize its position up to one width/height. |
Unshuffle()
The Unshuffle() method restores the layers of the control in case they were shuffled.
Update(callback, thisArgopt)
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.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
callback |
callback | Indicates a callback to perform changes within the control. | |
thisArg |
any |
<optional> |
Specifies the value of "this" keyword during the callback. If missing/empty/undefined the thisArg points to the control itself, as an object of Gauge type. |
Example
oGauge.Update(function()
{
// performs multiple changes to the control
});off(event, listener, methodopt)
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).
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
event |
string | Indicates the event to unbind, which can either be:
|
|
listener |
object | callback | Defines the listener to remove, which can either be:
|
|
method |
string |
<optional> |
Defines an optional case-sensitive string specifying the method on the listener to remove. If not provided, the listener[type]() function is used. This parameter is ignored when the listener is a JavaScript callback function. |
- Since:
- 4.4
Example
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();on(event, listener, methodopt) → {object}
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.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
event |
string | Specifies the event to listen for or a keyboard shortcut, in one of the following forms:
|
|
listener |
object | callback | Defines the listener to add, which can either be:
|
|
method |
string |
<optional> |
Defines an optional case-sensitive string specifying the method on the listener to handle the event. If not provided, the listener[type]() function is used. This parameter is ignored when the listener is a JavaScript callback function. |
- Since:
- 4.4
Returns:
Returns the listeners of the specified type, as an exontrol.Arr({callback, thisArg, lock, name, equal}) type, which includes the following new members:
- type {string}, specifies a case-sensitive string that specifies the type of event to listen for
- do(event) {callback}, indicates a function that can be invoked to trigger the specified event for all listeners registered for that event type
- callback {callback}, defines the listener's callback function
- thisArg {any}, defines the value of this during the listener's callback execution
- lock {number}, locks or unlocks the invocation of the listener's callback
- name {string}, defines the name of the callback, mostly used for debugging purposes
- equal(oCompareListenerCallback) {callback}, indicates a function of callback(oCompareListenerCallback) {boolean} type compares the current object with the provided object. It returns true if the objects contain the same data
- Type
- object
Example
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);
});Events
onanchorclick
The onanchorclick() event occurs once the user clicks an anchor element (the <a id;options> ex-HTML part marks an anchor or hyperlink element).
Parameters:
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
oEvent |
object | Holds information about anchor being clicked.
Properties
|
- Since:
- 2.2
Example
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);
})onchange
The onchange() method occurs when the layer's value is changed.
Parameters:
| Name | Type | Description |
|---|---|---|
oEvent |
Layer | Specifies an object of Layer type whose value/offset-x/offset-y/rotation-angle has been changed. |
Example
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 typeonclick
The onclick() method occurs once the user clicks a selectable layer.
Parameters:
| Name | Type | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
oEvent |
object | Holds information about the click event as an object of {layer,dblClick,button,modifiers} type.
Properties
|
Example
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 typeondrag
The ondrag() method occurs once the layer has been dragged to a new position.
Parameters:
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
oEvent |
object | Holds information about the layer being dragged, as an object of {layer,event} type.
Properties
|
Example
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 typeondragend
The ondragend() method notifies that dragging the layer ends.
Parameters:
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
oEvent |
object | Holds information about the layer being dragged, as an object of {layer,event} type.
Properties
|
Example
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 typeondragstart
The onDragStart() method notifies that the user starts draggging the layer.
Parameters:
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
oEvent |
object | Holds information about the layer to drag, as an object of {layer,cancel,event} type.
Properties
|
Example
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 typeonlayerin
The onlayerin() method notifies that the cursor enters the layer.
Parameters:
| Name | Type | Description |
|---|---|---|
oEvent |
Layer | Indicates an object of Layer that specifies the layer. |
Example
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 typeonlayerout
The onlayerout() method notifies that the cursor exits the layer.
Parameters:
| Name | Type | Description |
|---|---|---|
oEvent |
Layer | Indicates an object of Layer that specifies the layer. |
Example
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