Surface class

Surface(client, oOptsopt)

new Surface(client, oOptsopt)

The ExSurface/JS lets you organize your objects to a surface. You can use the tool to generate organigrams, diagrams, graphs, flowcharts and so on. The ExSurface/JS is a HTML standalone-component, written in JavaScript, that uses no third-party libraries.

Every option of the Surface.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:
oSurface.Options = {allowActions: "scroll"}
oSurface.SetOptions({allowActions: "scroll"})
oSurface.AllowActions = "scroll"
oSurface.SetAllowActions("scroll")
where oSurface is an object of Surface 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
oOpts object <optional>
 An object of Surface.Options type that defines different options to display the control.
Requires:
  • module:exontrol.commmon.min.js

Requires

  • module:exontrol.commmon.min.js

Classes

Options

Members

(static, readonly) CoordEnum :number

The CoordEnum type defines the type of coordinates the elements of the surface supports. The CoordEnum type supports the following values:
Type:
  • number
Properties:
Name value Type Description
exDefCoord 0 number The positive coordinates are shown right-down to origin of the surface.
exCartesian 1 number The elements show in Cartesian coordinates. The positive coordinates are shown right-up to origin of the surface.
exAllowPositiveOnly 16 number Only the positive panel of the surface is shown. The exAllowPositiveOnly flag can be combined with exDefCoord or exCartesian value. For instance, the exCartesian + exAllowPositiveOnly indicates that surface displays only the positive coordinates in Cartesian system.
Since:
  • 1.3

(static, readonly) LinkControlPointEnum :number

The LinkControlPointEnum type specifies the link's control points. The LinkControlPointEnum type supports the following values:
Type:
  • number
Properties:
Name value Type Description
exNoControlPoint 0 number The link displays no control points
exStartControlPoint 1 number The link shows control point that changes the link's StartPos property (the exStartControlPoint point is marked with black squares)
exEndControlPoint 2 number The link shows control point that changes the link's EndPos property (the exEndControlPoint point is marked with black squares)
exControlPoint 4 number Defines the corners of the link's path. You can remove a exControlPoint points by dragging to another, so intermediate exControlPoint points are removed. You can move all control points of the link at once, if SHIFT key is pressed (the exControlPoint points are marked black circles)
exMiddleControlPoint 8 number Defines the link's middle control points that are displayed between two exControlPoint points, to let the use add new exControlPoint points, to redefine the link's path (The exMiddleControlPoint points are marked with gray circles)
exOrthoArrange 16 number Specifies that the lines of the link are orthogonal arranged when the user drags and drops the middle or control-points of the path (excludes the start/end control-points)
exAllowChangeFrom 32 number Allows the user to adjust the link's from element by dragging and dropping the start control point (requires the exStartControlPoint flag)
exAllowChangeTo 64 number Indicates that the user can adjust the link's to element by dragging and dropping the end control point (requires the exEndControlPoint flag)

(static, readonly) SingleSelEnum :number

The Surface.SingleSelEnum type defines flags the singleSel/SetSingleSel/GetSingleSel method uses.
Type:
  • number
Properties:
Name value Type Description
exDisableSel 0 number The exDisableSel value specifies that the control's selection is disabled.
exEnableSel 1 number The exEnableSel flag specifies that the control's selection is enabled (multiple-selection, unless the exSingleSel is set ).
exSingleSel 2 number The exSingleSel flag specifies that the user can select a element only.
exToggleSel 4 number The exToggleSel flag specifies that the element's selection state is toggled once the user clicks a element.
exDisableCtrlSel 8 number The exDisableCtrlSel flag disables toggling the element's selection state when user clicks a element, while CTRL modifier key is pressed.
exDisableShiftSel 16 number The exDisableShiftSel flag disables selecting elements using the SHIFT key.
exDisableDrag 32 number The exDisableDrag flag disables selecting elements by drag.

(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 Surface.type member always returns "Surface"
Type:
  • string
Since:
  • 1.8
Example
console.log(exontrol.Surface.type); // logs "Surface"

(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.Surface.version); // displays the version of the control, for instance "5.2"

CanRedo

The CanRedo() method indicates whether the control can perform a Redo operation.
Since:
  • 2.0
Example
false {boolean}, no Redo operation is permitted
true {boolean}, a Redo operation is available
CanRedo

CanUndo

The CanUndo() method indicates whether the control can perform an Undo operation.
Since:
  • 2.0
Example
false {boolean}, no Undo operation is permitted
true {boolean}, an Undo operation is available
CanUndo

EndBlockUndoRedo

The EndBlockUndoRedo() method ends recording the Undo/Redo operations as a block. You can use the StartBlockUndoRedo / EndBlockUndoRedo methods to group multiple Undo/Redo operations into a single-block. The AllowUndoRedo property enables or disables the Undo/Redo feature.
Since:
  • 2.0
Example
oControl.StartBlockUndoRedo()
   ...
 oControl.EndBlockUndoRedo()
EndBlockUndoRedo

GetAllowUndoRedo

The GetAllowUndoRedo() method specifies whether the Undo/Redo feature is enabled or disabled. To undo an action you need to press Ctrl+Z, while for to redo something you've undone, press Ctrl+Y.
Since:
  • 2.0
Example
false {boolean}, the Undo/Redo feature is disabled (by default)
true {boolean}, the Undo/Redo feature is enabled.
GetAllowUndoRedo

GetUndoRedoQueueLength

The GetUndoRedoQueueLength() method gets the maximum number of Undo/Redo actions that may be stored to the control's Undo/Redo queue.
Since:
  • 2.0
Example
-1 {number}, the Undo/Redo queue is limitless
1 {number}, the Undo/Redo queue limits the number of actions to store to 1 (one action or one block of actions)
GetUndoRedoQueueLength

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:

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

The following sample displays the element being clicked:

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

or

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

where oSurface is an object of Surface type
Listeners

Redo

The Redo() method redoes the last action that was undone (reverses the Undo method). The Undo and Redo features let you remove or repeat single or multiple UI actions, but all actions must be undone or redone in the order you did or undid them – you can't skip actions.
Since:
  • 2.0
Example
Redo(), redoes the last action that was undone
Redo

SetAllowUndoRedo

The SetAllowUndoRedo() method enables or disables the Undo/Redo feature (by default the Undo/Redo feature is disabled). The Undo and Redo features let you remove or repeat single or multiple actions, but all actions must be undone or redone in the order you did or undid them – you can't skip actions. For example, if you added three elements and then decide you want to undo the first change you made, you must undo all three changes. To undo an action you need to press Ctrl+Z, while for to redo something you've undone, press Ctrl+Y.
Since:
  • 2.0
Example
false {boolean}, the Undo/Redo feature is disabled (by default)
true {boolean}, enables the Undo/Redo feature.
SetAllowUndoRedo

SetUndoRedoQueueLength

The SetUndoRedoQueueLength() method limits the Undo/Redo queue.
Since:
  • 2.0
Example
-1 {number}, the Undo/Redo queue is limitless
1 {number}, the Undo/Redo queue limits the number of actions to store to 1 (one action or one block of actions)
SetUndoRedoQueueLength

Shortcuts :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 removes the selection (calls the RemoveSelection() method) once the user presses the Delete key:

oSurface.Shortcuts.Add( "Delete", oSurface.RemoveSelection, oSurface );

where oSurface is an object of Surface type
Shortcuts

StartBlockUndoRedo

The StartBlockUndoRedo() method records all next Undo/Redo operations into a block until the EndBlockUndoRedo method is called. You can use the StartBlockUndoRedo / EndBlockUndoRedo methods to group multiple Undo/Redo operations into a single-block. The AllowUndoRedo property enables or disables the Undo/Redo feature.
Since:
  • 2.0
Example
oControl.StartBlockUndoRedo()
   ...
 oControl.EndBlockUndoRedo()
StartBlockUndoRedo

Undo

The Undo() method undoes the last action or a sequence of actions. For instance, if an element has been moved, Undo means moves back the element to its position before move. The Undo and Redo features let you remove or repeat single or multiple UI actions, but all actions must be undone or redone in the order you did or undid them – you can't skip actions.
Since:
  • 2.0
Example
Undo(), undoes the last control operation
Undo

Zoom :number

The Zoom property defines the zoom factor of the control's content. The zoom factor determines how much the control's content is magnified or reduced. Once the user adjusts the browser's zoom level, the control automatically recalculates its zoom factor to maintain the correct scaling of its content. The ZoomLevels property defines the allowed zoom levels the user can select from.
Type:
  • number
Example
null {null}, Specifies normal-view (100%)
150 {number}, Indicates that the control's label is magnfied to 150%
Zoom

oSV :SV

Holds the control's surface view as an object of SV type.
Type:
oSV

Methods

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
oSurface.BeginUpdate();
  // performs multiple changes to the control
oSurface.EndUpdate();
BeginUpdate

BlockUndoRedo(callback, thisArg)

The BlockUndoRedo() method records the Undo/Redo operations as a block. The BlockUndoRedo() method calls StartBlockUndoRedo / EndBlockUndoRedo methods.
Parameters:
Name Type Description
callback callback Specifies a function of callback() type.
thisArg any Indicates the value of "this" keyword during the callback, or the control itself if missing.

Element(id) → {Element}

The Element() method gets the element giving its index, identifier/key or reference.
Parameters:
Name Type Description
id any The id parameter could be any of the following:
  • id {number}, indicates a numeric value that defines the index of the element to request
  • id {string}, specifies a string expression that defines the identifier/key/plain-caption of the element to request
  • id {Element}, specifies the object reference to the element to request for
Since:
  • 1.1
Returns:
Returns null if the element is not found, or an object of Element type, if the elements collection contains the giving id.
Type
Element

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
oSurface.BeginUpdate();
 // performs multiple changes to the control
oSurface.EndUpdate();
EndUpdate

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 elements
  • expand/collapse elements
  • 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"
Since:
  • 1.8
Returns:
Returns a string that encodes the current UI layout for the entire object
Type
string
Example
The following statements are equivalents:

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

where oSurface is an object of Surface type
GetLayout

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: 588x412
Zoom: 100%
Element: 16/21
Link: 10/10
Sel: 0
Type
string

GroupUndoRedoActions(countopt)

The GroupUndoRedoActions() method groups the next to current Undo/Redo actions into a single block.
Parameters:
Name Type Attributes Description
count number <optional>
 Indicates the number of actions to group (if missing all actions are grouped).
Since:
  • 2.0
Example
GroupUndoRedoActions(), groups all Undo/Redo operations into a block
GroupUndoRedoActions
The Link() method gets the link giving its index, identifier/key or reference.
Parameters:
Name Type Description
id any The id parameter could be any of the following:
  • id {number}, indicates a numeric value that defines the index of the link to request
  • id {string}, specifies a string expression that defines the identifier/key/plain-caption of the link to request
  • id {Link}, specifies the object reference to the link to request for
Since:
  • 1.1
Returns:
Returns null if the link is not found, or an object of Link type, if the links collection contains the giving id.
Type
Link

RedoListAction(actionopt, countopt) → {string}

The RedoListAction() method gets the Redo actions that can be performed.
Parameters:
Name Type Attributes Description
action string <optional>
 Specifies null(to list all Redo actions) or the mask-pattern to match the action to list. Space sparates multiple mask-pattern. The mask-pattern supports wild characters as explained:
  • * (Any), masks any combination of characters
  • ? (Alphabetic), masks a letter such as [a-z] or [A-Z]
  • # (Digit), masks a digit character, [0-9]
  • [...] (Alternative), masks any characters that are contained in the [] brackets. For instance, the [abcA-C] mask
count number <optional>
 Indicates the number of Redo actions to list (if missing all Redo actions are listed).
Since:
  • 2.0
Returns:
Returns the list of Redo actions that can be performed
Type
string
Example
RedoListAction(), lists all Redo actions that can be executed
  RedoListAction("*Element"), lists all "*Element" Redo actions that can be executed, such as AddElement, RemoveElement, UpdateElement or MoveElement
  RedoListAction("AddElement"), lists first "AddElement" Redo actions that can be executed
RedoListAction

RedoRemoveAction(actionopt, countopt)

The RedoRemoveAction() method removes the first actions from the Redo queue.
Parameters:
Name Type Attributes Description
action string <optional>
 Specifies null(to remove all Redo actions) or the mask-pattern to match the action to remove. Space sparates multiple mask-pattern. The mask-pattern supports wild characters as explained:
  • * (Any), masks any combination of characters
  • ? (Alphabetic), masks a letter such as [a-z] or [A-Z]
  • # (Digit), masks a digit character, [0-9]
  • [...] (Alternative), masks any characters that are contained in the [] brackets. For instance, the [abcA-C] mask
count number <optional>
 Indicates the number of actions to remove (if missing all actions are removed) from the Redo queue.
Since:
  • 2.0
Example
RedoRemoveAction(), removes all actions from the Redo queue
  RedoRemoveAction("*Element"), removes all "*Element" actions, such as AddElement, RemoveElement, UpdateElement or MoveElement, from the Redo queue
  RedoRemoveAction("AddElement"), removes the first "AddElement" Redo action from the Redo queue
RedoRemoveAction

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 elements
  • expand/collapse elements
  • 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
Since:
  • 1.8

UndoListAction(actionopt, countopt) → {string}

The UndoListAction() method gets the Undo actions that can be performed.
Parameters:
Name Type Attributes Description
action string <optional>
 Specifies null(to list all Undo actions) or the mask-pattern to match the action to list. Space sparates multiple mask-pattern. The mask-pattern supports wild characters as explained:
  • * (Any), masks any combination of characters
  • ? (Alphabetic), masks a letter such as [a-z] or [A-Z]
  • # (Digit), masks a digit character, [0-9]
  • [...] (Alternative), masks any characters that are contained in the [] brackets. For instance, the [abcA-C] mask
count number <optional>
 Indicates the number of Undo actions to list (if missing all Undo actions are listed).
Since:
  • 2.0
Returns:
Returns the list of Undo actions that can be performed
Type
string
Example
UndoListAction(), lists all Undo actions that can be executed
  UndoListAction("*Element"), lists all "*Element" Undo actions that can be executed, such as AddElement, RemoveElement, UpdateElement or MoveElement.
  UndoListAction("AddElement",1), lists first "AddElement" Undo actions that can be executed
UndoListAction

UndoRemoveAction(actionopt, countopt)

The UndoRemoveAction() method removes the last actions from the Undo queue.
Parameters:
Name Type Attributes Description
action string <optional>
 Specifies null(to remove all Undo actions) or the mask-pattern to match the action to remove. Space sparates multiple mask-pattern. The mask-pattern supports wild characters as explained:
  • * (Any), masks any combination of characters
  • ? (Alphabetic), masks a letter such as [a-z] or [A-Z]
  • # (Digit), masks a digit character, [0-9]
  • [...] (Alternative), masks any characters that are contained in the [] brackets. For instance, the [abcA-C] mask
count number <optional>
 Indicates the number of actions to remove (if missing all actions are removed) from the Undo queue.
Since:
  • 2.0
Example
UndoRemoveAction(), removes all actions from the Undo queue
  UndoRemoveAction("*Element"), removes all "*Element" actions, such as AddElement, RemoveElement, UpdateElement or MoveElement, from the Undo queue
  UndoRemoveAction("AddElement"), removes the first "AddElement" Undo action from the Undo queue
UndoRemoveAction

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 Surface type.
Example
oSurface.Update(function()
{
 // performs multiple changes to the control
});
Update

feE(callback, thisArgopt)

The feE/forEachElement() method invokes the callback for each element of the control (enumerates the elements, as they were added).
Parameters:
Name Type Attributes Description
callback callback A function of callback(oElement) type that's called for every element, where oElement is:
  • oElement {Element}, specifies an element of Element 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 Surface type.
Since:
  • 4.0
Example
Below is a sample showing the captions for all elements:

oSurface.feE(function(oElement)
{
   console.log(oElement.Caption)
})
feE

feEU(callback, thisArgopt) → {any}

The feEU/forEachElementUntil() method invokes the callback for each element of the control, until the callback returns a truthy value (enumerates the elements, as they were added).
Parameters:
Name Type Attributes Description
callback callback A function of callback(oElement) {any} type that's called for every element, where oElement is
  • oElement {Element}, specifies an element of Element 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 Tree type.
Since:
  • 4.0
Returns:
Returns the last-value of the callback
Type
any
Example
The following sample displays the caption of the first non-movable element:

console.log(oSurface.feEU(function(oElement)
{
   return !oElement.isMovable() && oElement.Caption || "";
}))
feEU

feL(callback, thisArgopt)

The feL/forEachLink() method invokes the callback for each link of the control (enumerates the links, as they were added).
Parameters:
Name Type Attributes Description
callback callback A function of callback(oLink) type that's called for every link, where oLink is:
  • oLink {Link}, specifies an link of Link 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 Surface type.
Since:
  • 4.0
Example
Below is a sample showing the all links (from, to):

oSurface.feL(function(oLink)
{
   console.log(oLink.From, "-&gt;", oLink.To)
})
feL

feLU(callback, thisArgopt) → {any}

The feLU/forEachLinkUntil() method invokes the callback for each link of the control, until the callback returns a truthy value (enumerates the links, as they were added).
Parameters:
Name Type Attributes Description
callback callback A function of callback(oLink) {any} type that's called for every link, where oLink is
  • oLink {Link}, specifies an link of Link 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 Tree type.
Since:
  • 4.0
Returns:
Returns the last-value of the callback
Type
any
Example
The following sample displays the first hidden link:

console.log(oSurface.feLU(function(oLink)
{
   return !oLink.isVisible() && (oLink.From + "-&gt;" + oLink.To) || "";
}))
feLU

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:
  • event {string}, the name of the event to unbind. 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.
  • event {string}, a string that encloses a shortcut in {}, such as "{Ctrl + A}", to unbind the keyboard shortcut
listener object | callback Defines the listener to remove, which can either be:
  • listener {callback}, a JavaScript callback function that was previously bound to the event (the method parameter has no effect)
  • listener {object}, an object that implements a notification method (e.g., listener[method](oEvent) or listener[type](oEvent)) that was previously used to handle the event
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:

oSurface.off("click");

where oSurface is an object of Surface type.

This sample is equivalent to:

oSurface.Listeners.Remove("onclick");

The following example removes all event handlers from the control:

oSurface.off();

where oSurface is an object of Surface type.

This sample is equivalent to:

oSurface.Listeners.Clear();

or

oSurface.Listeners.Remove();
off

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:
  • If the value is in the "{shortcut}" form (for example, "{Ctrl + A}"), it defines a keyboard shortcut. The callback is triggered when that key combination is pressed. To provide keyboard support for the component, the <canvas> element that hosts it needs to be focusable. To achieve this, you must include the tabIndex attribute in the canvas HTML tag (for example, <canvas tabIndex="0"></canvas>).

    See Shortcuts for more information. (for example, on("{Ctrl + A}", callback)). The shortcut-feature for on/off methods is supported from version 5.0.

  • Otherwise, the value is treated as a standard event name (for example, "click"), and the callback is invoked when that event occurs on the component. 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.

    See Listeners for more information. (for example, on("click", callback)).
listener object | callback Defines the listener to add, which can either be:
  • listener {callback}, a JavaScript callback function to handle the event directly (the method parameter has not effect)
  • listener {object}, an object that implements a notification method (e.g., listener[method](oEvent) or listener[type](oEvent)) to handle the event when it occurs
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
where:
  • 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:

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

where oSurface is an object of Surface type.

This sample is quivalent of 

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