Rollist class

Rollist(host, oOptionsopt)

new Rollist(host, oOptionsopt)

The ExRollist/JS component is an interactive list control that arranges its items along the path of an ellipse. As users navigate through the list, the selected item is automatically positioned and displayed at the center of the control, ensuring maximum visibility and focus. This layout creates a smooth and visually engaging experience when browsing items.

Features include:

  • Elliptical Layout, items are arranged along an elliptical path for a modern, visually engaging presentation (supports liner arrangement as well)
  • Centered Selection, ihe selected item is always displayed in the center of the control for better visibility and focus
  • Smooth Scrolling & Animation, offers smooth, animated transitions when navigating through items
  • Filter Support, allows users to filter items dynamically as they type characters to match
  • Mouse & Touch Support, fully interactive via mouse wheel and touch gestures such as swipe or drag
  • Customizable Items, items can include rich HTML content, images, or custom styles
  • Keyboard Navigation, allows users to navigate the list using keyboard input (e.g., arrow keys)
  • Lightweight & Fast, designed for performance, even with large numbers of items
  • Responsive Design, automatically adapts to the size of its container for flexible integration
The ExRollist/JS is a HTML standalone-component, written in JavaScript, that uses no third-party libraries.

Every option of the Rollist.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:
oRollist.Options = {allowActions: "scroll"}
oRollist.SetOptions({allowActions: "scroll"})
oRollist.AllowActions = "scroll"
oRollist.SetAllowActions("scroll")
where oRollist is an object of Rollist type
Parameters:
Name Type Attributes Description
host any The host parameter specifies the HTML element hosting the control. It can be one of the following:
  • {string}, specifies the identifier of the document element hosting the control
  • {HTMLElement}, indicates the actual document element hosting the control
When the HTML element hosts the control, it automatically receives the class name 'exrollist'. Each item displayed within the control is assigned the class name 'exrolitem', and the item that is currently selected will have the class name 'selected'. You can use the following class names to customize the appearance of different elements within the control:
  • exrollist, this is the class name for the HTML element that serves as the container or host for the entire control. It wraps the entire control and holds all items.
  • exrolitem, this is the class name for each individual item within the control. It applies to the HTML elements that represent each item listed in the control. The Misc.tagName specifies the type of HTML element to be created for hosting the item. The className property of the item defines any additional class names to be applied to the HTML element, allowing for further customization of its styling.
  • selected', this is the additional class name applied to the currently selected item (exrolitem). The selected item is always positioned at the center of the control, making it the focal point of the interaction. You can use the Misc.selectPos to define the vertical ratio for where the selected item is displayed, ranging from -1 (top) to 1 (bottom), with 0 indicating the center
Additionally, the control supports the following classes:
  • exrolfilter, this is the class name for the HTML element that contains the control's filter. The filter allows the user to match typed characters. By default, the filter consists of a label, an input element, and a span. The label is used to specify a description, such as "Filter For...", the input (of type text-box) holds the filter pattern, and the span displays the close button. The structure is: "<label for='rofilter'></label><input type='textbox' id='rofilter'><span>&#10006;</span>". For example, the CSS rule ".exrolfilter label::after { content: 'Filter for: '; color: gray; }" shows "Filter For..." in gray to the left of the input. The Rollist#SetAllowFilterInput option specifies whether the control displays a filter bar, enabling the user to filter items by typing text.
  • exroloccur, this is the class name for the SPAN element that highlights matching patterns within the items, allowing customization. By default, the highlight appears with a yellow background.
  • hidden, this is the class name used to hide HTML elements. By default, the CSS rule is {display: none;}
oOptions object <optional>
 An object of Rollist.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) AllowFilterInputEnum :number

The Rollist.AllowFilterInputEnum type defines the options and flags that control the visibility of the filter input in the control.
Type:
  • number
Properties:
Name value Type Description
exHide 0 number No filter input is visible
exAlwaysVisible 1 number The filter input is always visible, the close button is not displayed
exShowOnAnyKey 2 number Displays the filter input when the user presses a key, along with a close button. Requires the HTML element hosting the control to include the tabindex attribute to receive keyboard focus.
exDisableHighlightOccurences 16 number Disables the highlighting of all occurrences of the typed text within the items, which otherwise helps users visually identify matching content.

(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 Rollist.type member always returns "Rollist"
Type:
  • string

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

Listeners :exontrol.Lts

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

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

The following samples handle the "onload" event:

oRollist.Listeners.Add("onload", function (oEvent)
{
 console.log(oEvent);
});

or

oRollist.on("load", function (oEvent)
{
 console.log(oEvent);
});

where oRollist is an object of Rollist type
Listeners

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

CloseFilterInput()

The CloseFilterInput() method hides and clears the filter input field, effectively removing it from view and disabling the filtering functionality. It also clears any active filter.

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

GetAllowActions() → {string}

The GetAllowActions() method gets the actions the user can perform once the control is clicked or touched. The order of the actions is very important, as the control checks each action from left to right until it finds a matching action for the performed mouse/touch event. The first matched action is performed, and the rest of the actions are ignored. So if you want to perform a specific action once the user clicks an item, and perform another action if the user clicks an area that does not contain any item, you should place the first action before the second one in the AllowActions property.
Returns:
Returns the actions the user can perform once the control is clicked or touched. The order of the actions is very important, as the control checks each action from left to right until it finds a matching action for the performed mouse/touch event. The first matched action is performed, and the rest of the actions are ignored. So if you want to perform a specific action once the user clicks an item, and perform another action if the user clicks an area that does not contain any item, you should place the first action before the second one in the AllowActions property.

The format of the property is:

"action(shortcut,shortcut,...),action(shortcut,shortcut,...)..."
where
  • "action", defines the action to perform (as defined below)

    Action Description Flags
    "scroll" Scrolls the control by drag and drop

  • "shortcut", defines the event's button or/and the modifier-keys that are required to perform the action. The "shortcut" is a combination of none, one or more of the following values:
    • "Shift", indicates that the SHIFT key is pressed
    • "Ctrl" or "Control", indicates that the CTRL key is pressed
    • "Alt" or "Menu", indicates that the ALT key is pressed
    • "Meta" , indicates that the META key is pressed
    • "LButton", specifies that the mouse's left-button is pressed
    • "RButton", specifies that the mouse's right-button is pressed
    • "MButton", specifies that the mouse's middle/wheel-button is pressed
    • "Long", specifies that the action requires a "long" click or touch before it begins
    • "Double", specifies that the action requires a "double" click before it begins (this flag is available for non-dragable actions only such as "edit")
    • "+", indicates AND between values
Type
string

GetAllowFilterInput() → {Rollist.AllowFilterInputEnum}

The GetAllowFilterInput() method specifies whether the control displays a filter bar, enabling the user to filter items that contain the typed text.
Returns:
Returns a value from the AllowFilterInputEnum that indicates the current filter input mode. Possible values include:
  • exHide (0), no filter input is visible
  • exAlwaysVisible (1), the filter input is always visible, without a close button
  • exShowOnAnyKey (2), displays the filter input when the user presses any key, including a close button. Requires the host HTML element to have a tabindex attribute for keyboard focus
  • exDisableHighlightOccurences (0x10), disables the highlighting of all occurrences of the typed text within the items, which otherwise helps users visually identify matching content.
Type
Rollist.AllowFilterInputEnum

GetCyclic() → {boolean}

The GetCyclic() method indicates whether the items are displayed in a continuous loop.
Returns:
Returns true if the items are displayed in a continuous loop
Type
boolean

GetFilter() → {string}

The GetFilter() method specifies the filter to be applied to the items, ensuring that only items matching the filter criteria are shown.
Returns:
Returns the filter to be applied to the items
Type
string

GetItems() → {Items}

The GetItems() method returns the control's items.
Returns:
Returns an object of Items type.
Type
Items
Example
The following statements are equivalents:

 oRollist.GetItems() {Items}, returns the control's items
 oRollist.Items {Items}, returns the control's items

where oRollist is an object of Rollist type
GetItems

GetMisc() → {MiscellaneousOptions}

The GetMisc() method indicates the control's miscellaneous options.
Returns:
Returns the control's miscellaneous options
Type
MiscellaneousOptions

GetOptions() → {object}

The GetOptions() method returns the current options of the control.
Returns:
An object of Rollist.Options type that indicates the options to display the control.
Type
object

GetSelect() → {Item}

The GetSelect() method gets the item that is currently selected, which is always displayed at the center of the control.
Returns:
Returns the selected item, which is always displayed at the center of the control
Type
Item

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

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 equivalents:

 oRollist.GetWheelChange() {number}, returns the amount the control scrolls when the user rolls the mouse wheel
 oRollist.WheelChange {number}, returns the amount the control scrolls when the user rolls the mouse wheel

where oRollist is an object of Rollist type
GetWheelChange

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 | RegExp specifies the delimiter, which can be a character, string, or regular expression (@since 4.4), used to identify the end of a row, item, or line during parsing (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 header (has effect only if format field is "CSV").

Item(id) → {Item}

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

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
oRollist.Refresh(), refreshes the control
Refresh

SetAllowActions(value)

The SetAllowActions() method customizes the actions the user can perform once the control is clicked or touched. The order of the actions is very important, as the control checks each action from left to right until it finds a matching action for the performed mouse/touch event. The first matched action is performed, and the rest of the actions are ignored. So if you want to perform a specific action once the user clicks an item, and perform another action if the user clicks an area that does not contain any item, you should place the first action before the second one in the AllowActions property.
Parameters:
Name Type Description
value string Indicates the actions the user can perform once the control is clicked or touched.

The format of the property is:

"action(shortcut,shortcut,...),action(shortcut,shortcut,...)..."
where
  • "action", defines the action to perform (as defined below)

    Action Description Flags
    "scroll" Scrolls the control by drag and drop

  • "shortcut", defines the event's button or/and the modifier-keys that are required to perform the action. The "shortcut" is a combination of none, one or more of the following values:
    • "Shift", indicates that the SHIFT key is pressed
    • "Ctrl" or "Control", indicates that the CTRL key is pressed
    • "Alt" or "Menu", indicates that the ALT key is pressed
    • "Meta" , indicates that the META key is pressed
    • "LButton", specifies that the mouse's left-button is pressed
    • "RButton", specifies that the mouse's right-button is pressed
    • "MButton", specifies that the mouse's middle/wheel-button is pressed
    • "Long", specifies that the action requires a "long" click or touch before it begins
    • "Double", specifies that the action requires a "double" click before it begins (this flag is available for non-dragable actions only such as "edit")
    • "+", indicates AND between values
Example
null {null}, indicates the control's default allowActions value
"" {string}, specifies that no operation is allowed once the user clicks or touches the control
"scroll" {string}, specifies that only "scroll" operation is allowed, no matter of the event's button or modifier-keys is pressed.
SetAllowActions

SetAllowFilterInput(value)

The SetAllowFilterInput() method specifies whether the control displays a filter bar, enabling the user to filter items by typing text. The ShowFilterInput programmatically displays the filter input field of the control.
Parameters:
Name Type Description
value Rollist.AllowFilterInputEnum Specifies how the filter input is displayed, as one of the following:
  • exHide (0), no filter input is visible
  • exAlwaysVisible (1), the filter input is always visible, without a close button
  • exShowOnAnyKey (2), displays the filter input when the user presses any key, including a close button. Requires the host HTML element to have a tabindex attribute for keyboard focus
  • exDisableHighlightOccurences (0x10), disables the highlighting of all occurrences of the typed text within the items, which otherwise helps users visually identify matching content.
Example
null {null} or "hide" {string} or exontrol.Rollist.AllowFilterInputEnum.exHide {AllowFilterInputEnum} or 0 {number}, no filter input is visible (by default)
"always" {string} or exontrol.Rollist.AllowFilterInputEnum.exAlwaysVisible {AllowFilterInputEnum} or 1 {number}, indicates that the filter input is always visible
"key,disable" {string} or (exontrol.Rollist.AllowFilterInputEnum.exShowOnAnyKey | exontrol.Rollist.AllowFilterInputEnum.exDisableHighlightOccurences) {AllowFilterInputEnum} or 0x12 {number}, shows the filter input when the user presses any key and disables the highlighting of all occurrences of the typed text in the items
SetAllowFilterInput

SetCyclic(value)

The SetCyclic() method indicates whether the items are displayed in a continuous loop.
Parameters:
Name Type Description
value boolean Indicates whether the items are displayed in a continuous loop.

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
Example
"data.txt" {string}, imports data from data.txt file
SetData

SetFilter(value)

The SetFilter() method specifies the filter to be applied to the items, ensuring that only items matching the filter criteria are shown.
Parameters:
Name Type Description
value string Specifies the filter to be applied to the items.
Example
null {null} or "" {string}, clear the filter (if applied)
"icon" {string}, filters the items to display only those that contain the word 'icon'
SetFilter

SetMisc(value)

The SetMisc() method defines the control's miscellaneous options.
Parameters:
Name Type Description
value MiscellaneousOptions A value that indicates the control's miscellaneous options.

SetOptions(nOptions, bIncludeAllopt) → {boolean}

The SetOptions() method applies new options to the view.
Parameters:
Name Type Attributes Description
nOptions object Specifies an object of Rollist.Options type that indicates the new options to apply.
bIncludeAll boolean <optional>
 Indicates whether all fields of nOptions are included in the item's oOptions object.
Returns:
Returns true, if there were options applied to the item
Type
boolean
Example
oRollist.Options = {imageAlign: 1, imageSize: 24}, changes the alignment and the size for all images within the control.

The oRollist.Options = value statement is equivalent with oRollist.SetOptions(value) or oRollist.SetOptions(value)
SetOptions

SetSelect(value)

The SetSelect() method sets the item that is currently selected, which is always displayed at the center of the control.
Parameters:
Name Type Description
value any Indicates one of the following:
  • {number}, specifies the position of the item to select
  • {string}, specifies the identifier/key of the item to select
  • {Item}, indicates the item to select

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.
SetSmooth

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
18 {number}, scrolls the control by 18-pixels when mouse's wheel is rotated (CTRL + wheel scrolls horizontally)
SetWheelChange

ShowFilterInput()

The ShowFilterInput() method displays the filter input field, enabling the user to type keywords for filtering items. This allows the user to narrow down the list by matching the typed words with the items displayed.

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

feI(callback, thisArgopt)

The feI/forEachItem() method invokes the callback for each item of the control.
Parameters:
Name Type Attributes Description
callback callback A function of callback(oItem) type that's called for every item, where oItem is:
  • oItem {Item}, specifies an item of Item 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 Rollist type.

feIU(callback, thisArgopt) → {any}

The feIU/forEachItemUnit() method invokes the callback for each item of the control, until the callback returns a not-empty value.
Parameters:
Name Type Attributes Description
callback callback A function of callback(oItem) {any} type that's called for every item, where oItem is
  • oItem {Item}, specifies an item of Item 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 Rollist type.
Returns:
Returns the last-value of the callback
Type
any

getInnerHTML(oItem,) → {string}

The getInnerHTML() method retrieves the inner HTML content of the HTML element associated with the specified item. You can override this function to gain more control over which HTML elements are displayed based on the item's content or value.
Parameters:
Name Type Description
oItem, Item Indicates the item whose associated inner HTML is being requested.
Returns:
Returns the inner HTML of the HTML element associated with the given item.
Type
string

item(position) → {Item}

The item() method retrieves an item based on its position within the Items collection (not to be confused with Item method that gets the item by its index or identifier/key).
Parameters:
Name Type Description
position number The zero-based index of the item to retrieve.
Returns:
The item at the specified position, or undefined if the position is invalid.
Type
Item

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, 'load' is equivalent to 'onload' 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 load event handler from the control:

oRollist.off("load");

where oRollist is an object of Rollist type.

This sample is equivalent to:

oRollist.Listeners.Remove("onload");

The following example removes all event handlers from the control:

oRollist.off();

where oRollist is an object of Rollist type.

This sample is equivalent to:

oRollist.Listeners.Clear();

or

oRollist.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, "load"), 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, 'load' is equivalent to 'onload' and vice versa.

    See Listeners for more information. (for example, on("load", 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 sample shows how you can handle the onload event:

oRollist.on("load", function()
{
  console.log("onload event occured");
});

where oRollist is an object of Rollist type.

This sample is quivalent of 

oRollist.Listeners.Add("onload", function ()
{
  console.log("onload event occured");
});
on

Events

onadditem

The onadditem() method notifies your application that a new item has been added to the control.
Parameters:
Name Type Description
oItem Item Indicates an object of Item type being added.
Example
The following samples display the item being added:

oRollist.onadditem = function (oItem)
{
 console.log(oItem);
}

or

oRollist.Listeners.Add("onadditem", function (oItem)
{
 console.log(oItem);
})

or

oRollist.on("additem", function (oItem)
{
 console.log(oItem);
})

where oRollist is an object of Rollist type
onadditem

onclick

The onclick event occurs once the user clicks or double-clicks the control.
Parameters:
Name Type Description
oEvent object specifies an object of {dblClick,button,modifiers,item,html} type, that holds information about the object being clicked.
Properties
Name Type Description
item Item specifies undefined or an object of Item type that indicates the clicked item.
html HTMLElement specifies undefined or an object of HTMLElement type that indicates the HTML element associated with the clicked item.
dblClick boolean indicates whether the user clicks or double-clicks the item.
button number indicates which button is pressed while clicking the item as 1 (left), 2 (right) or 4 (middle).
modifiers number specifies a combination of 1, 2, 4 and 16 according with modifier keys (ALT, CTRL, META and SHIFT), or 0 if no modifier keys.
Example
The following samples show how you can handle the "click" event:

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

or

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

or

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

where oRollist is an object of Rollist type.
onclick

oncreate

The oncreate() method occurs once an HTML element is created and linked to a visible item. You can use this event to associate or set additional properties or options for the newly created element.
Parameters:
Name Type Description
oEvent oEvent Defines the HTML element being constructed for a visible item, represented as an object with properties: {item,html}, where item is of type Item and html is of type HTMLElement.
Properties
Name Type Description
item Item Specifies the item for which the HTML element is generated.
html HTMLElement Indicates the HTML element associated with the item.
Example
The following samples sets the HTML element's tooltip:

oRollist.oncreate = function (oEvent)
{
 oEvent.html.title = oEvent.html.innerText;
}

or

oRollist.Listeners.Add("oncreate", function (oEvent)
{
 oEvent.html.title = oEvent.html.innerText;
})

or

oRollist.on("create", function (oEvent)
{
 oEvent.html.title = oEvent.html.innerText;
})

where oRollist is an object of Rollist type
oncreate

ondestroy

The ondestroy() method occurs when the associated HTML element is removed from the DOM.
Parameters:
Name Type Description
oEvent oEvent Defines the {item,html} object representing the HTML element to be removed, which was created for a visible item.
Properties
Name Type Description
item Item Specifies the item for which the HTML element is generated.
html HTMLElement Specifies the HTML element associated with the item that is to be removed.
Example
The following samples displays the element being destroyed:

oRollist.ondestroy = function (oEvent)
{
 console.log(oEvent);
}

or

oRollist.Listeners.Add("ondestroy", function (oEvent)
{
 console.log(oEvent);
})

or

oRollist.on("destroy", function (oEvent)
{
 console.log(oEvent);
})

where oRollist is an object of Rollist type
ondestroy

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:

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

or

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

or

oRollist.on("error", function (oEvent)
{
 console.log(oEvent);
})

where oRollist is an object of Rollist type
onerror

onfilter

The onfilter() method notifies your application when the user applies or clears filters, such as by typing into the control's filter input.
Parameters:
Name Type Description
filter string Indicates the destroyed HTML element.
Example
The following samples displays the current filter once the user changes it:

oRollist.Listeners.Add("onfilter", function (oEvent)
{
 console.log(oEvent);
})

or

oRollist.on("filter", function (oEvent)
{
 console.log(oEvent);
})

or

oRollist.onfilter = function (oEvent)
{
 console.log(oEvent);
}

where oRollist is an object of Rollist type.
onfilter

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):

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

or

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

or

oRollist.on("load", function ()
{
 alert("onload");
})

where oRollist is an object of Rollist type
onload

onremoveitem

The onremoveitem() method occurs once an item has been removed from the Items collection.
Parameters:
Name Type Description
oItem Item Indicates an object of Item type being removed.
Example
The following samples display the item being removed:

oRollist.onremoveitem = function (oItem)
{
 console.log(oItem);
}

or

oRollist.Listeners.Add("onremoveitem", function (oItem)
{
 console.log(oItem);
})

or

oRollist.on("removeitem", function (oItem)
{
 console.log(oItem);
})

where oRollist is an object of Rollist type
onremoveitem

onselect

The onselect() method notifies your application once the user selects an item at runtime (clicks an item).
Parameters:
Name Type Description
oEvent object Indicates the item being selected as an object of Item type.
Example
The following samples show how you can handle the "select" event:

oRollist.Listeners.Add("onselect", function (oEvent)
{
 console.log(oEvent);
})

or

oRollist.on("select", function (oEvent)
{
 console.log(oEvent);
})

or

oRollist.onselect = function (oEvent)
{
 console.log(oEvent);
}

where oRollist is an object of Rollist type.
onselect