/* @license Copyright (C) Exontrol. All rights reserved. */

/////////////////////////////////////////////////////////// (exontrol.Rollist)
//
//  The exontrol.Rollist class provides the following fields (public):
//
//    Listeners {object}, holds a reference to exontrol.Lts which defines the items of the control.
//
//  The exontrol.Rollist class provides the following methods (public):
//
//    BeginUpdate(), prevents invalidating the control until the EndUpdate() method is called
//    EndUpdate(), resumes invalidating the control
//    Refresh(), refreshes the control
//    Update(callback, thisArg), locks the control's update during the callback, and invalidates the control once the method ends.
//    Items/GetItems() {exontrol.Rollist.Item}, returns the control's items.
//    Item(id) {exontrol.Rollist.Item}, returns the item based on its index or identifier.
//    Import(source, importOpts), imports data from CSV format
//
//    Options/GetOptions()/SetOptions(value) {object}, specifies the options of the exontrol.Rollist control
//    WheelChange/GetWheelChange()/SetWheelChange(value) {number}, defines the amount the control scrolls when the user rolls the mouse wheel.
//    AllowActions/GetAllowActions()/SetAllowActions(value) {string}, customizes the actions the user can perform once the control is clicked or touched.
//    GetSmooth()/SetSmooth(value), defines the time in ms the control goes from one layout to another.
//    Data/SetData(value) {any}, loads the control's data from CSV files
//    Misc/GetMisc()/SetMisc(value) {MiscellaneousOptions}, defines the control's miscellaneous options
//    Select/GetSelect()/SetSelect(value) {any}, defines the position of the item that is currently selected, which is always displayed at the center of the control
//    Cyclic/GetCyclic()/SetCyclic(value) {boolean}, indicates whether the items are displayed in a continuous loop
//    Filter/GetFilter()/SetFilter(value) {string}, specifies the filter to be applied to the items, ensuring that only items matching the filter criteria are shown
//    AllowFilterInput/GetAllowFilterInput()/SetAllowFilterInput(value) {AllowFilterInputEnum}, specifies whether the control displays a filter bar, enabling the user to filter items that contain the typed text
//    ShowFilterInput(), displays the filter input field, enabling the user to type keywords for filtering items
//    CloseFilterInput(), hides and clears the filter input field, effectively removing it from view and disabling the filtering functionality.
//
//  The exontrol.Rollist class provides the following items (through Listeners):
//
//     "onadditem", notifies your application once a new item has been added. The onadditem's parameter is:
//
//        oEvent {Item}, indicates an object of Item type that defines the item being added
//
//     "onremoveitem", notifies your application once an item has been removed. The onremoveitem's parameter is:
//
//        oEvent {Item}, indicates an object of Item type that defines the item being added
//
//     "oncreate", 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. The oncreate's parameter is:
//
//        oEvent {object}, 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
//
//          oEvent.item {Item}, specifies the item for which the HTML element is generated 
//          oEvent.html {HTMLElement}, indicates the HTML element associated with the item
//
//     "ondestroy", occurs when the associated HTML element is removed from the DOM. The ondestroy's parameter is:
//
//        oEvent {object}, represents the pair to be removed, constructed for a visible item, as an object of {item,html} type
//
//          oEvent.item {Item}, specifies the item for which the HTML element was created 
//          oEvent.html {HTMLElement}, indicates the HTML element associated with the item, to be removed
//
//     "onselect", occurs once the user selects an item. The onselect's parameter is:
//
//        oEvent {Item}, indicates an object of Item type that defines the item being clicked
//
//     "onclick", occurs once the user clicks or double-clicks the control. The onclick's parameter is:
//
//        oEvent {object}, specifies an object of {dblClick,button,modifiers,item,html} type, that holds information about the object being clicked
//
//          oEvent.item {Item}, specifies undefined or an object of Item type that indicates the clicked item
//          oEvent.html {HTMLElement}, specifies undefined or an object of HTMLElement type that indicates the HTML element associated with the clicked item
//          oEvent.dblClick {boolean}, indicates whether the user clicks or double-clicks the item
//          oEvent.button {number}, indicates which button is pressed while clicking the item as 1 (left), 2 (right) or 4 (middle)
//          oEvent.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
//
//     "onfilter", notifies your application when the user applies or clears filters, such as by typing into the control's filter input. The onfilter's parameter is:
//
//        oEvent {string}, specifies the new filter being applied (if the filter has been cleared, this will be undefined)
//
//     "onload", notifies your application once the control loads/imports data. The onload event has no parameters.
//     "onerror", notifies your application once the control encountered an error. The onerror's parameter is:
//
//        oEvent {DOMException}, an object of DOMException (or any other) type that holds information about the error
//
///////////////////////////////////////////////////////////

/////////////////////////////////////////////////////////// (exontrol.Def.Rollist)
//
// The exontrol.Def.Rollist namespace provides definitions for different objects, primitives, objects of exontrol.Rollist object
//
//  The exontrol.Def.Rollist namespace provides the following fields:
//
//    wheelChange {number}, specifies the amount the control scrolls when the user rolls the mouse wheel.
//    allowActions {string}, customizes the actions the user can perform once the user clicks or touches the control.
//    smooth {number}, defines the time in ms the control goes from one layout to another.
//    data {any}, imports the control's data from CSV files
//    allowDrop {boolean}, specifies whether the user can drag and drop local files into the control
//    misc {MiscellaneousOptions}, holds the control's miscellaneous options
//    select {any}, defines the position of the item that is currently selected, which is always displayed at the center of the control
//    cyclic {boolean}, indicates whether the items are displayed in a continuous loop
//    filter {string}, specifies the filter to be applied to the items, ensuring that only items matching the filter criteria are shown
//    allowFilterInput {AllowFilterInputEnum}, specifies whether the control displays a filter bar, enabling the user to filter items that contain the typed text
//
///////////////////////////////////////////////////////////

/**
 * @description The exontrol.Def.Rollist namespace provides definitions for different objects, primitives, objects of exontrol.Rollist object
*/
exontrol.Def.Rollist =
{
  /**
  * @description The wheelChange field specifies the amount the control scrolls when the user rolls the mouse wheel.
  * @type {number}
  * @example
  * 
  *   0 {number}, locks any action the mouse's wheel performs
  *   1 {number}, scrolls the control by 1-item when mouse's wheel is rotated
  */
  wheelChange: 1,
  /**
   * @description The allowActions field customizes the actions the user can perform once the user clicks or touches the control.
   * 
   * The format of allowActions field is:
   * 
   *  "action(shortcut,shortcut,...),action(shortcut,shortcut,...)..."
   * 
   * where
   * 
   *  "action", indicates the name of the action. The "action" can have any of the following values:
   * 
   *    "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}
   * @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.
   * 
  */
  allowActions: "scroll",
  /**
   * @description The smooth field defines the time in ms the control goes from one layout to another.
   * @type {number}
   * @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.
  */
  smooth: null,
  /**
   * @description The data field defines the source the control imports data from, 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
   * 
   * @type {any}
   * @example
   * 
   * "sample.csv" {string}, imports data from sample.csv file
  */
  data: null,
  /**
   * @description The misc field holds the control's miscellaneous options, as an object of MiscellaneousOptions type
   * @type {MiscellaneousOptions}
  */
  misc: 
  {
    /**
     * @description The hAlign field specifies the horizontal alignment of roll items along the top edge of the control, as a positive value. 
     * <ul>
     * <li>A value of 0 aligns the items near the top-left corner</li>
     * <li>A value of 1 aligns them near the top-right corner</li>
     * <li>A value of 0.5 places them at the top-center</li>
     * <li>Values greater than 1 align the items beyond the top-right corner</li>
     * </ul>
     * @type {number}
     * @example
     * 
     *  null {null} or 0.25 {number}, the roll-items go to the top-center of the control
     *  1 {number}, the roll-items go to the top-right corner of the control
     * 
    */
    hAlign: 0.25,
    /**
     * @description The vAlign field specifies a positive value that determines the vertical position of the top edge of the rectangle. 
     * <ul>
     *  <li>A value of 0 keeps the top edge at its initial position</li>
     *  <li>A value of 1 shifts the top edge downward by the height of the rectangle</li>
     *  <li>A value of 2 shifts it downward by twice the rectangle's height</li>
     *  <li>Higher values continue shifting it further down accordingly</li>
     * </ul>
     * @type {number}
     * @example
     * 
     *  null {null} or 0 {number}, keeps the top edge at its initial position
     *  1 {number}, shifts the top edge downward by the height of the rectangle
     * 
    */
    vAlign: 0,
    /**
     * @description The tagName field defines the type of HTML items to create within the control. The item's className property specifies an additional class name to apply to the HTML element that hosts the item
     * @type {string}
     * @example
     * 
     *  null {null} or "pre" {string}, specifies that items are hosted in <pre> HTML elements by default
     *  "div" {string}, indicates that items are hosted in <div> HTML elements
     * 
    */
    tagName: "pre",
    /**
     * @description The selectPos field defines the vertical ratio for where the selected item is displayed, ranging from -1 (top) to 1 (bottom), with 0 indicating the center.
     * <ul>
     *  <li>A value between 0 and -1 positions the selected item progressively closer to the top of the control</li>
     *  <li>A value of 0 centers the selected item within the control</li>
     *  <li>A value between 0 and 1 positions the selected item progressively closer to the bottom of the control</li>
     * </ul>
     * @type {number}
     * @example
     * 
     *  null {null} or 0 {number}, centers the selected item
     *  -1 {number}, always displays the selected item at the top of the control
     * 
    */
    selectPos: 0,
    /**
     * @description The gradualOpacity field defines a 'from-to' pair representing a gradual opacity transition, where the 'from' value is applied near the center (at the selectPos position), and the 'to' value is applied to the surrounding area. The gradualOpacityTransition field defines the transition effect applied by the gradualOpacity option.
     * @type {string}
     * @example
     * 
     *  undefined {undefined}, null {null} or "" {string}, no effect (by default)
     *  "1 - 0.25" {string}, results in an opacity transition from 1 (fully opaque) at the center (selectPos) to 0.75 (slightly transparent) toward the edges
     *  0.5 {number}, semi-transparent for all
     * 
    */
    gradualOpacity: undefined,
    /**
     * @description The gradualOpacityTransition field defines the transition effect applied by the gradualOpacity option. It accepts one of the following values:
     * <ul>
     *  <li>"linear" {string}, applies a constant-speed (linear) transition
     *  <li>"ease" {string}, applies a smooth transition that starts slowly, speeds up, then slows down
     *  <li>"ease-in" {string}, applies a transition that starts slowly and then accelerates
     *  <li>"ease-out" {string}, applies a transition that starts quickly and then decelerates
     *  <li>"ease-in-out" {string}, applies a transition that starts and ends slowly, with a faster middle phase
     *  <li>"ease-in-out-expo" {string}, applies a more dramatic ease-in-out transition with exponential acceleration and deceleration
     *  <li>"swipe" {string}, applies a custom swipe-like transition using a bezier curve
     * <ul>
     * Alternatively, a custom bezier curve can be specified using an array of four values:
     * <blockquote>
     *  [P1.x, P1.y, P2.x, P2.y]
     * </blockquote>
     * This defines the two control points P1 and P2 for the cubic bezier curve used during the transition. The x-values of both P1 and P2 must be between 0 and 1, as required for valid CSS timing functions. You can use the exontrol.Bezier control to effortlessly visualize or define various transition types.
     * 
     * @type {(string|array)}
     * @example
     * 
     *  undefined {undefined}, null {null} or "ease" {string}, defined the default transtion to "ease"
     *  "ease-in" {string}, applies a transition that starts slowly and then accelerates
     *  [0,1,1,0] {array}, creates a custom-transition
     * 
    */
    gradualOpacityTranstion: "ease",
    /**
     * @description The zIndex() method specifies the stacking order of items along the z-axis (which is like the "depth" in a 2D page)
     * @type {number}
     * @example
     * 
     *  9999 {number}, sets the starting stacking order for the items
    */
    zIndex: 9999,
  },
  /**
   * @description The select field defines the position of the item that is currently selected, which is always displayed at the center of the control
   * @type {any}
   * @example
   * 
   *  0 {number} or null {null}, selects the first item based on its position in the Items collection (0-based)
   *  Item(0) {Item}, selects the first item by index from the Items collection
   * 
  */
  select: null,
  /**
   * @description The cyclic field indicates whether the items are displayed in a continuous loop
   * @type {boolean}
   * @example
   * 
   *  false {boolean}, no effect (by default)
   *  true {boolean}, specifies that the items are displayed in a continuous loop
   * 
  */
  cyclic: false,
  /**
   * @description The filter field specifies the filter to be applied to the items, ensuring that only items matching the filter criteria are shown
   * @type {any}
   * @example
   * 
   *  null {null} or "" {string}, clears the fiter if any
   *  "icon" {string}, displays only items that include the word 'icon' in their content
   * 
  */
  filter: null,
  /**
   * @description The allowFilterInput field specifies whether the control displays a filter bar, enabling the user to filter items by typing text.
   * @type {Rollist.AllowFilterInputEnum}
   * @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
   * 
  */
  allowFilterInput: null,
}

/////////////////////////////////////////////////////////// (exontrol.Rollist.ImportOptions)
//
// The exontrol.Rollist.ImportOptions type defines options to import data from CSV format. A comma-separated values (CSV) file is a delimited text file that uses a comma to separate values. Each line of the file is a data record. Each record consists of one or more fields, separated by commas
//
// The exontrol.Rollist.ImportOptions type supports the following fields:
//
//  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 header (has effect only if format field is "CSV")
//
///////////////////////////////////////////////////////////

exontrol.Rollist.ImportOptions = 
{
  /**
   * @description The limit field specifies the maximum number of rows/items/lines to import
   * @type {number}
   * @example
   * 
   *  undefined {undefined}, specifies unlimited number of rows/items/lines to import
   *  1000 {number}, limits the items to import to 1,000
  */
  limit: undefined,
  /**
   * @description The format field specifies the format of source to import data form
   * @type {string}
   * @example
   * 
   *  null {null}, specifies that the source of import is an array of [[value]] type
   *  "CSV" {string}, specifies that the source of import is a string in CSV format
  */
  format: null,
  /**
   * @description The eor (EndOfRow) field 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")
   * @type {string}
   * @example
   * 
   *  ";" {string}, indicates that the ; (semicolon) character ends each row/item/line
   *  /^[ \t]*\r\n/m {RegExp}, empty lines delimites each item (match blank lines that contain only spaces or tabs, followed by a Windows-style newline \r\n)
  */
  eor: "\r\n",
  /**
   * @description The eof (EndOfField) field specifies the character to separate fields within the row/item/line (has effect only if format field is "CSV")
   * @type {string}
   * @example
   * 
   *  "\t" {string}, specifies TAB charactar as field separator
  */
  eof: null,
  /**
   * @description The str field specifies the character to quote values (has effect only if format field is "CSV")
   * @type {string}
   * @example
   * 
   *  "'" {string}, specifies ' character to quote any value that contains other ' or eof character
  */
  str: null,
  /**
   * @description The hdr field specifies whether the first line indicates the control's header (has effect only if format field is "CSV")
   * @type {boolean}
   * @example
   * 
   *  false {boolean}, specifies the no header line is provided
   *  true {boolean}, the first line defines the control's header
  */
  hdr: false
}

/////////////////////////////////////////////////////////// (exontrol.Rollist.Item)
//
// The exontrol.Rollist.Item object holds a collection of exontrol.Rollist.Item type (item of the control)
//
// The exontrol.Rollist.Item object provides the following methods:
//
//  Add(oItemOpts) {exontrol.Rollist.Item}, creates and adds a new item into the control
//  Count/GetCount() {number}, returns the number of items within the collection.
//  Item(id) {exontrol.Rollist.Item}, gets the item giving its index, identifier/key or reference
//  Remove(id), removes the item giving its index, identifier/key or reference
//  Clear(), removes all items of the control
//
/////////////////////////////////////////////////////////// 

/////////////////////////////////////////////////////////// (exontrol.Rollist.Item)
//
// The exontrol.Rollist.Item object holds information(options) about an item within the control.
//
// The exontrol.Rollist.Item object provides the following methods:
//
//  Remove(), removes the item itself from items collection ( equivalent of Items.Remove(id) method )
//  Options/GetOptions()/SetOptions(value) {exontrol.Rollist.ItemOptions}, indicates the item's options (at once) such as visibility, position and so on
//  Index/GetIndex() {number}, returns the index of the item (0-based)
//  Position/GetPosition()/SetPosition(value) {number}, specifies the item's position (0-based)
//  Value/GetValue()/SetValue(value) {any}, defines the value of the item
//  Key/GetKey()/SetKey(value) {any}, specifies the item's key (the Items.Item(key) requests an item by its index, identifier/key or reference)
//  Visible/GetVisible()/SetVisible(value) {boolean}, shows or hides the item
//  ClassName/GetClassName()/SetClassName(value) {string}, specifies an additional class name to apply to the HTML element that hosts the item
//
/////////////////////////////////////////////////////////// 

/////////////////////////////////////////////////////////// (exontrol.Rollist.ItemOptions)
//
//  The exontrol.Rollist.ItemOptions type holds all options an item can display or own
//
//  The exontrol.Rollist.ItemOptions type defines the following fields:
//
//    value {any}, defines the item's value
//    visible {boolean}, indicates whether the item is visible or hidden
//    key {string}, specifies the key associated with the item
//    position {number}, specifies the item's position
//    className {string}, specifies an additional class name to apply to the HTML element that hosts the item
//
///////////////////////////////////////////////////////////

exontrol.Rollist.ItemOptions = 
{
  /**
   * @description The value field defines the value of the item.
   * @type {any}
   * 
   * @example
   * 
   *  Add("caption") {Item}, adds the "caption" item
   *  Add({value: "caption"}) {Item}, adds the "caption" item
   * 
  */
  value: undefined,
  /**
   * @description The visible field indicates whether the item is visible or hidden.
   * @type {boolean}
   * @example
   * 
   *  false {boolean}, hides the item
   *  true {boolean}, shows the item
  */
  visible: true,
  /**
   * @description The key field specifies the key associated with the item. Specifies the key associated with the item. If no key is provided, the item's plain-caption can be used to request an item. The plain-caption includes no ex-HTML tags, such as <b>, <fgcolor> and so on
   * @type {string}
   * @example
   * 
   *  "logo" {string}, defines the item with the giving key (logo). You can use the Items.Item("logo") method to request the item giving its key.
  */
  key: null,
  /**
   * @description The position field specifies the item's position.
   * @type {number}
   * @example
   * 
   *  null {null}, the null value has no effect
   *  0 {number}, moves the item on the first position
   * 
  */
  position: null,
  /**
   * @description The className field specifies an additional class name to apply to the HTML element that hosts the item. By default, the 'exrolitem' class name is applied to the HTML element that hosts the roll item.
   * @type {string}
   * @example
   * 
   *  null {null} or "" {string}, no extra class name applied
   *  "red" {string}, appends 'red' to the HTML element's class name, applying the .red style to the item
   * 
  */
  className: null,
};