Graph class

Graph(client, oOptionsopt)

new Graph(client, oOptionsopt)

The ExGraph/JS component provides xxx. Features include:
  • Feature 1
  • Feature 2
  • and much more
The ExGraph/JS is a HTML standalone-component, written in JavaScript, that uses no third-party libraries.

Every option of the Graph.Options type has associated a property of the control. For instance, the option:

allowActions {string}, customizes the actions the user can perform once the user clicks or touches the control
is associated with the property:
AllowActions {string}, customizes the actions the user can perform once the user clicks or touches the control
which means that the following statements are equivalent:
oGraph.Options = {allowActions: "scroll"}
oGraph.SetOptions({allowActions: "scroll"})
oGraph.AllowActions = "scroll"
oGraph.SetAllowActions("scroll")
where oGraph is an object of Graph type
Parameters:
Name Type Attributes Description
client any The client parameter indicates the control's client area as:
  • array of [x,y,width,height] type that specifies the control's client area
  • string, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
  • HTMLCanvasElement, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
oOptions object <optional>
 An object of Graph.Options type that defines different options to display the control.
Requires:
  • module:exontrol.commmon.min.js
Graph

Requires

  • module:exontrol.commmon.min.js

Classes

Options

Members

Listeners :exontrol.Lts

The Listeners field defines the series 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 series the control supports. The Series section lists the series the component supports.
Type:
  • exontrol.Lts
Example
The following sample shows how you can get all series the component currently supports:

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

The following sample displays information about the serie being clicked:

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

where oGraph is an object of Graph type
Listeners

Shortcuts :exontrol.Sts

The Shortcuts field defines the shortcuts of the control, as an object of exontrol.Sts type. 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
Shortcuts

oGV :GV

The oGV field defines the base graph-view of control. Use the AddGraphView() method to add a new view to the control. Use the RemoveGraphView() method removes a graph-view already created by AddGraphView() method.
Type:
oGV

(static, readonly) LegendAlignEnum :number

The Graph.LegendAlignEnum type specifies the alignment of the legend's content.
Type:
  • number
Properties:
Name value Type Description
exStart 0 number The legend's content is aligned to the left or top side of the view
exCenter 1 number The legend's content is centered
exEnd 2 number The legend's content is aligned to the right or bottom side of the view

(static, readonly) LegendFlowEnum :number

The Graph.LegendFlowEnum type determines whether the legend objects are arranged from left to right or top to bottom.
Type:
  • number
Properties:
Name value Type Description
exAuto -1 number The legend items are arranged horizontally from left to right when the legend panel is anchored to the top/bottom side of the view. Alternatively, they are arranged vertically from top to bottom when the legend panel is anchored to the left/right side of the view.
exLeftToRight 0 number The exLeftToRight mode indicates that the next legend object gets arranged to the right of the current legend object
exTopToBottom 1 number The exTopToBottom mode indicates that the next legend object gets arranged to the bottom of the current legend object

(static, readonly) LegendSymbolAlignmentEnum :number

The Graph.LegendSymbolAlignmentEnum type defines the alignment of the symbol of the serie relative to the label of the serie.
Type:
  • number
Properties:
Name value Type Description
exHide 0 number Hides the symbols of the series
exTop 1 number The symbol of the serie is shown on the top of the label. The exTop flag can be combined with exStart, exCenter or exEnd values.
exBottom 2 number The symbol of the serie is shown below the label. The exBottom flag can be combined with exStart, exCenter or exEnd values.
exLeft 3 number The symbol of the serie is shown to the left of the label. The exLeft flag can be combined with exStart, exCenter or exEnd values.
exRight 4 number The symbol of the serie is shown to the right of the label. The exRight flag can be combined with exStart, exCenter or exEnd values.
exFill 5 number The symbol of the serie is shown on the label's background (no extra space is allocated)
exStart 0 number The symbol of the serie is left/top-aligned relative to the label. The exStart flag can be combined with exTop, exBottom, exLeft or exRight values.
exCenter 16 number The symbol of the serie is centered relative to the label. The exCenter flag can be combined with exTop, exBottom, exLeft or exRight values.
exEnd 32 number The symbol of the serie is right/bottom-aligned relative to the label. The exEnd flag can be combined with exTop, exBottom, exLeft or exRight values.

(static, readonly) PanelDockEnum :number

The Graph.PanelDockEnum type defines the edge the legend or overview panel is anchored to.
Type:
  • number
Properties:
Name value Type Description
exTop 1 number The legend(overview) is anchored to the top side of the view
exBottom 2 number The legend(overview) is anchored to the bottom side of the view
exLeft 3 number The legend(overview) is anchored to the left side of the view
exRight 4 number The legend(overview) is anchored to the right side of the view

(static, readonly) SerieStyleEnum :number

The Graph.SerieStyleEnum type indicates the way the values of the serie get connected.
Type:
  • number
Properties:
Name value Type Description
exNormal 0 number The values get connected with straight line
exSpline 1 number The values get connected with a spline curve

(static, readonly) ShowCursorCategoryLineEnum :number

The Graph.ShowCursorCategoryLineEnum type defines the flags to show the vertical/horizontal category/x-line, when the crosshair cursor hovers the chart.
Type:
  • number
Properties:
Name value Type Description
exHide 0 number The vertical/horizontal category/x-line is hidden
exShowNear 1 number The vertical/horizontal category/x-line is shown when the pointer is near the category
exShowAsIs 2 number The vertical/horizontal category/x-line is shown at pointer position (default)

(static, readonly) ShowCursorSerieTooltipEnum :number

The Graph.ShowCursorSerieTooltipEnum type defines the flags to show the tooltips, when the crosshair cursor hovers the charts of the series.
Type:
  • number
Properties:
Name value Type Description
exHide 0 number No tooltip is displayed when the crosshair cursor hovers the chart
exShowNear 1 number The vertical/horizontal category/x-line indicates the series whose tooltip is displayed, when the crosshair cursor hovers the chart
exShowExact 2 number The pointer indicates the series whose tooltip is displayed, when the crosshair cursor hovers its chart
exShowAll 3 number Displays all tooltips for all series of the category unit being indicated by the vertical/horizontal category/x-line

(static, readonly) ShowValueEnum :number

The Graph.ShowValueEnum type indicates the flags to show value on the chart.
Type:
  • number
Properties:
Name value Type Description
exHide 0 number No point, line or value is shown
exPoint 1 number Specifies that the value-point is displayed. The valuePoint shape defines the visual appearance of the value-point.
exLine 2 number Specifies that the guided line to value is displayed. The valueLine shape defines the visual appearance of the guided line to value
exValue 4 number Indicates that the value itself is shown
exHideIfEmpty 128 number Hides the value-point, value-line and value itself if the value is empty

(static) type :string

The type field defines the full-name of the object (the constructor.name does not give the same name for minimized forms). The Graph.type member always returns "Graph"
Type:
  • string

(static) version :string

The version field defines the version of the control. The current version is 3.1
Type:
  • string

Methods

AddGraphView(name, attributesopt) → {GV}

The AddGraphView() method creates a new view to display the series. Use the RemoveGraphView() method removes a graph-view already created by AddGraphView() method.
Parameters:
Name Type Attributes Description
name string defines the name of the graph-view to be created. It must be an unique name. The "graph" defines the control's default-graph view, and it is reserved. If missing, the "graph.split" is used instead
attributes exontrol.W.Options <optional>
 A exontrol.W.Options that defines the attributes of the window
Properties
Name Type Description
Visible boolean The Visible field indicates whether the window is visible or hidden.
VisibleExtends string The VisibleExtends field specifies the list of windows the current window depends to be visible or hidden. A string expression that specifies the list of windows the current window's visibility depends on as explained:
  • if the VisibleExtends property includes the window itself, the window is visible if any window in VisibleExtends is visible, else
  • if the VisibleExtends property does NOT includes the window itself, the window is hidden if any window in VisibleExtends is hidden (or the window is visible if all VisibleExtends windows are visible)
AllowKeys boolean The AllowKeys field specifies whether the window can receive the Keys series. By default, only the canvas window receives all the keys.
Enabled boolean The Enabled field specifies whether the window is enabled or disabled (the window is protected and shown in gray).
Resizable boolean The Resizable field indicates whether the window is resizable or fixed.
Locked boolean The Locked field specifies that the window is locked (the window is protected).
Dock exontrol.WDT The Dock field specifies how the control borders are docked to its parent control and determines how a control is resized with its parent. The exontrol.WDT type supports the following values:
  • N(0), the window is not docked (none)
  • T(1), the window's top edge is docked to the top of its containing window (top)
  • B(2), the window's bottom edge is docked to the bottom of its containing window (bottom)
  • L(3), the window's left edge is docked to the left edge of its containing window (left)
  • R(4), the window's right edge is docked to the right edge of its containing window (right)
  • F(5), all the window's edges are docked to all edges of its containing window and sized appropriately (fill)
Size number The Size field defines the width/height of the window when it is docked.
SizeExtends string The SizeExtends field specifies the list of windows that shares the same size. Once a window is resized, all its SizeExtends windows are sized the same as the current one.
Client Array.<number> The Client field specifies position of the window relative to the parent window, as an array of [x,y,width,heigh] type.
Background string The Background field defines the window's background color ( CSS Color ) or null/undefined if not provided.
Foreground string The Foreground field defines the window's foreground color ( CSS Color ) or null/undefined if not provided.
Opacity number The Opacity field indicates the window's opacity, as a number between 0 and 1 (1 is not transparent at all, 0.5 is 50% see-through, and 0 is completely transparent)
HoverBackground string The HoverBackground field, defines the window's background color while the cursor hovers it ( CSS Color ) or null/undefined if not provided
HoverForeground string The HoverForeground field defines the window's foreground color while the cursor hovers it( CSS Color ) or null/undefined if not provided
HoverOpacity number The HoverOpacity field indicates the window's opacity, as a number between 0 and 1 (1 is not transparent at all, 0.5 is 50% see-through, and 0 is completely transparent), when the cursor hovers it
DrawWindowFrame boolean The DrawWindowFrame field indicates whether the window draws its frame.
Extends string The Extends field indicates a list of windows separated by comma character to extend the current's client area to. The windows(child windows) must have the z-order greater than the z-order of the current window, else they will be ignored. The Extends field changes the z-order of the windows as well.
HoverExtends string The HoverExtends field specifies the list of windows separated by comma character that receives the hover-series once the cursor hovers the current window.
AllowXChg boolean The AllowXChg field specifies whether the window can exchange its UI position with another window. Only windows with AllowXChg field set can be exchanged.
XChgID string The XChgID field specifies the general expression, whose evaluated result defines the caption to be displayed on the window's anchor-exchange part. The expression supports keywords like index, name and shortname, that indicates the window's index, a value starting from 0, the window's name and short-name. The evaluated result can include exontrol's HTML tags that will be applied on the window's anchor-exchange element. If the expression is not valid, the XChgID value is used as it is.
Control object The Control field defines the control associated with the window (for internal use only).
HScroll string The HScroll field defines window's horizontal scroll bar. A string expression that indicates the name of the window that hosts an exontrol.SB control or an object of exontrol.SB type that defines the window's horizontal scroll bar (for internal use only).
VScroll string The VScroll field defines window's vertical scroll bar. A string expression that indicates the name of the window that hosts an exontrol.SB control or an object of exontrol.SB type that defines the window's vertical scroll bar (for internal use only).
Layout string The Layout field defines the properties (separated by comma) the GetLayout/SetLayout methods of CW saves/restores (for internal use only).
Returns:
Returns the newly created view as an object of GV type. Returns null, in case there is already a window with specified name.
Type
GV
Example
oGraph.AddGraphView("2nd",{Background: "black", Foreground: "white", Dock: 3}), adds a new graph-view panel, docked to the left-size, with a black-background and a white-foreground
AddGraphView

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. You can use the Update() method to perform multiple changes at once.
BeginUpdate

EndUpdate()

The EndUpdate() method resumes the control's render, after it is suspended by the BeginUpdate() method.
EndUpdate

GetCanvas() → {HTMLCanvasElement}

The GetCanvas() method returns the HTMLCanvasElement object where the control is currently running on.
Since:
  • 3.0
Returns:
Returns the HTMLCanvasElement object where the control is currently running on.
Type
HTMLCanvasElement
GetCanvas

GetLayout(oOptsopt) → {string}

The GetLayout() method saves the UI layout of the object to an encoded string. The layout can be restored using the SetLayout() method. Currently, the control's Layout property serializes the following:
  • layout of windows (size, dock, parent)
  • selected series
  • control's zoom
Parameters:
Name Type Attributes Description
oOpts object <optional>
 An object of {iMask,eMask,base64,equal,eol} type that defines options to serialize the properties of the container as explained bellow:
  • iMask {string}, specifies the mask (can include ? or * wild-characters) of properties to save
  • eMask {string}, specifies the mask (can include ? or * wild-characters) of properties to exclude from save
  • base64 {boolean}, Encodes the result to BASE 64
  • equal {string}, Indicates the separator between the name and the value. If missing, the = character is used
  • eol {string}, A character that separates the properties. By default it is "\n"
Returns:
Returns a string that encodes the current UI layout for the entire object
Type
string
Example
The following statements are equivalents:

 oGraph.GetLayout(), gets the control's layout
 oGraph.Layout, gets the control's layout

where oGraph is an object of Graph type
GetLayout

GetSeries() → {Series}

The GetSeries() method returns the control's series.
Returns:
Returns an object of Series type.
Type
Series
Example
The following statements are equivalents:

 oGraph.GetSeries() {Series}, returns the control's series
 oGraph.Series {Series}, returns the control's series

where oGraph is an object of Graph type
GetSeries

GetStatistics() → {string}

The GetStatistics() method gives statistics data of objects being hold by the control
Returns:
Returns statistics data of objects being hold by the control such as:
Size: 1,680x908
Zoom: 100%
Serie: 4/4
Compatibility: area-compat
Vertical: false
Length: 4x10
Type
string
Example
The following statements are equivalents:

 oGraph.GetStatistics(), gives statistics data of objects being hold by the control
 oGraph.Statistics, gives statistics data of objects being hold by the control

where oGraph is an object of Graph type
GetStatistics

GraphView(name) → {GV}

The GraphView() method gets the graph-view by name (which was previously created by the AddGraphView() method)
Parameters:
Name Type Description
name string defines the name of the graph-view to request ("graph" defines the control's default-graph view)
Returns:
Returns null or the an object of GV type associated with the name
Type
GV
GraphView

Import(source, importOptsopt)

The Import() method imports data from CSV format. The SetData(value) method is equivalent with Import(value) method.
Parameters:
Name Type Attributes Description
source any The source parameter may be one of the following:
  • A String expression that specifies the URL to a CSV file (contains no eof, eor or str)
  • A String expression in CSV format
  • An object that includes the "files" member of FileList type (a local file)
  • An array of data to load
importOpts object <optional>
 The importOpts parameter specifies options to import data into the control as object of ImportOptions type.
Properties
Name Type Description
limit number specifies the maximum number of rows/items/lines to import
format string determines the format of source to import data from
eor string specifies the characters the row/item/line ends (has effect only if format field is "CSV")
eof string specifies the character to separate fields within the row/item/line (has effect only if format field is "CSV")
str string specifies the character to quote values (has effect only if format field is "CSV")
hdr boolean indicates whether the first line in data represents the control's legend (has effect only if format field is "CSV")
Import

Refresh()

The Refresh() method refreshes the control
Refresh

RemoveGraphView(name)

The RemoveGraphView() method removes the view already created by the AddGraphView() method
Parameters:
Name Type Description
name string defines the name of the graph-view to be removed. The "graph" defines the control's default-graph view, and it can not be removed.
RemoveGraphView

Serie(id) → {Serie}

The Item() method returns the serie based on its index or identifier/key. The Serie(id) method is equivalent with Serie(id) method of the Series object
Parameters:
Name Type Description
id any The serie parameter could be any of the following:
  • serie {number}, indicates a numeric value that defines the index of the serie to request
  • serie {string}, specifies a string expression that defines the identifier/key of the serie to request
  • serie {Serie}, specifies the object reference to the serie to request for
Returns:
Returns null or an object of Serie type
Type
Serie
Serie

SetData(value)

Imports data from CSV files. The SetData(value) method is equivalent with Import(value) method. The ImportOptions type defines default options to import data.
Parameters:
Name Type Description
value any Indicates the source of the data, as one of the following:
  • A String expression that specifies the URL to a CSV file (contains no eof, eor or str)
  • A String expression in CSV format
  • An object that includes the "files" member of FileList type (a local file)
  • An array of data to load
The data source can be used by the Data property of the Serie object and categories option of the CategoryAxis property of the control.
Example
"data.txt" {string}, imports data from data.txt file
SetData

SetLayout(layout, oOptsopt)

The SetLayout() method restores the UI layout of the object from an encoded string, previously returned by the GetLayout() method. Currently, the control's Layout property serializes the following:
  • layout of windows (size, dock, parent)
  • selected series
  • control's zoom
Parameters:
Name Type Attributes Description
layout string A string expression that defines the UI layout to apply
oOpts object <optional>
 An object of {iMask,eMask,base64,equal,eol} type that defines options to serialize the UI layout as explained bellow:
  • iMask {string}, specifies the mask (can include ? or * wild-characters) of properties to load
  • eMask {string}, specifies the mask (can include ? or * wild-characters) of properties to exclude from load
  • base64 {boolean}, Decodes the layout from BASE 64
  • equal {string}, Indicates the separator between the name and the value. If missing, the = character is used
  • eol {string}, A sequence of characters that can separate the properties. By default, any of \n, \r or ; separates the properties
SetLayout

SetSeries(Specifies)

The SetSeries() method assigns the control's series
Parameters:
Name Type Description
Specifies object | SerieOptions | Array.<object> | Array.<SerieOptions> the series as an object (or an array of) of {category: value} or SerieOptions type
Example
{data: {"meta": 200, "whatsup": 300}} {object}, sets a single serie to represent, inluding the category names
 {data: [1,2,3,4]} {SerieOptions}, sets a single serie to represent
 [{data: [1,3,5,7]}, {data: "2,4,6,8"}] {SerieOptions[]}, sets multiple-series to represent
SetSeries

Update(callback, thisArgopt)

The Update() method locks the control's paint during the callback, and invalidates the control once the method ends.
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 Graph type
Update

feI(callback, thisArgopt)

The feI/forEachSerie() method invokes the callback for each serie of the control (unscrolled(top,bottom series) and scrolled series as well)
Parameters:
Name Type Attributes Description
callback callback A function of callback(oSerie) type that's called for every serie, where oSerie is:
  • oSerie {Serie}, specifies a serie of Serie type
thisArg any <optional>
 Indicates the value of "this" keyword during the callback. If missing/empty/undefined the thisArg points to the control itself, as an object of Graph type.
feI

feIU(callback, thisArgopt) → {any}

The feIU/forEachSerieUnit() method invokes the callback for each serie of the control (unscrolled(top,bottom series) and scrolled series as well), until the callback returns a not-empty value
Parameters:
Name Type Attributes Description
callback callback A function of callback(oSerie) {any} type that's called for every serie, where oSerie is
  • oSerie {Serie}, specifies a serie of Serie type
thisArg any <optional>
 Indicates the value of "this" keyword during the callback. If missing/empty/undefined the thisArg points to the control itself, as an object of Graph type.
Returns:
Returns the last-value of the callback
Type
any
feIU

Events

onerror

The onerror() method occurs once the control encountered an error.
Parameters:
Name Type Description
oEvent object Specifies an object of DOMException (or any other) type that holds information about the error
Example
The following samples display the error once it occurs:

oGraph.onerror = function (oEvent)
{
 console.log(oEvent);
}

or

oGraph.Listeners.Add("onerror", function (oEvent)
{
 console.log(oEvent);
})

where oGraph is an object of Graph type
onerror

onload

The onload() method occurs once the control loads or imports data
Example
The following samples display a message once the control loads or imports new data (for instance, the user drags and drops a file into the control):

oGraph.onload = function ()
{
 alert("onload");
}

or

oGraph.Listeners.Add("onload", function ()
{
 alert("onload");
})

where oGraph is an object of Graph type
onload