Options class (Rollist)

The allowActions field defines a list of actions separated by comma that the user can perform by drag or click on the control's content. 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

The allowActions field is mapped to the AllowActions property, which means that the following statements are equivalent:

oRollist.Options = {allowActions: "scroll(long)"}
oRollist.SetOptions({allowActions: "scroll(long)"})
oRollist.AllowActions = "scroll(long)"
oRollist.SetAllowActions("scroll(long)")

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.

The allowFilterInput field determines whether the control shows a filter bar, allowing users to filter items by typing text. The filter field defines the filter criteria, so only items that match are displayed. The filter bar usually includes an input field for entering filter text. The visibility and behavior of the filter input can be customized using the Rollist.AllowFilterInputEnum enumeration, which offers options to always show the filter, show it when the user types, or hide it completely. For instance, setting allowFilterInput to exShowOnAnyKey displays the filter input as soon as the user starts typing, enabling dynamic filtering of items. You can also combine this with exDisableHighlightOccurences to prevent the control from highlighting matching text, creating a cleaner appearance while filtering. By default, the allowFilterInput field is set to exHide, meaning that the filter input is not visible until the user performs an action that triggers its display (if configured to do so). The ShowFilterInput() method displays the filter input field, enabling the user to type keywords for filtering items. The CloseFilterInput() method hides the filter input field and clears any applied filter, showing all items again.

The allowFilterInput field is mapped to the AllowFilterInput property, which means that the following statements are equivalent:

oRollist.Options = {allowFilterInput: "key,disable"}
oRollist.SetOptions({allowFilterInput: "key,disable"})
oRollist.AllowFilterInput = "key,disable oRollist.SetAllowFilterInput("key,disable")

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

The cyclic field indicates whether the items are displayed in a continuous loop. By default, the cyclic field is set to false, meaning that the control does not loop through items. When cyclic is set to true, navigating past the last item will wrap around to the first item, and vice versa, creating a seamless browsing experience. This feature is particularly useful when you want to allow users to continuously scroll through items without hitting a hard stop at the end of the list.

The cyclic field is mapped to the Cyclic property, which means that the following statements are equivalent:

oRollist.Options = {cyclic: true}
oRollist.SetOptions({cyclic: true})
oRollist.Cyclic = true
oRollist.SetCyclic(true)

false {boolean}, no effect (by default)
true {boolean}, specifies that the items are displayed in a continuous loop

The data field defines the source the control imports data from diffent formats, such as CSV files, arrays of data, or FileList objects. The ImportOptions type defines the options used when importing data from a CSV source. Assigning a value to the data field clears the control's existing items before importing the new data. The control's Import() method processes the data specified in this field and populates the control's items accordingly. The data field can accept various types of input, allowing for flexible data loading options. For example, you can provide a string that specifies the URL to a CSV file, directly input CSV-formatted data as a string, use a FileList object to load data from a local file, or pass an array of data to be imported into the control. The Items.Add() method allows adding items one at a time, whereas the Import() method handles importing multiple items at once.

• A String expression that specifies the URL to a CSV file (the string includes no eof, eor or str fields of ImportOptions type), such as: "data.csv"
• A String expression in CSV format (eof, eor or str fields of ImportOptions type define delimiters and text qualifiers to be used in the CSV data), such as: "German\nEnglish\nFrench"
• An object that includes the "files" member of FileList type (a local file), such as: a drag-and-drop operation to drop a local file into the control can import data from that file
• An array of data to load, such as: ["German", "English", "French"]

The data field is mapped to the Data property, which means that the following statements are equivalent:

oRollist.Options = {data: "sample.csv"}
oRollist.SetOptions({data: "sample.csv"})
oRollist.Data = "sample.csv"
oRollist.SetData("sample.csv")

"sample.csv" {string}, imports data from sample.csv file using the default delimiters and text qualifiers for CSV format as defined in the ImportOptions type
["USA", "Germany", "France"] {array}, imports data from an array of strings

The filter field specifies the filter to be applied to the items, ensuring that only items matching the filter criteria are shown. The filter can be defined as a string that represents the text to match against the items' content. When a filter is applied, the control evaluates each item and displays only those that contain the specified filter text. For example, if you set the filter to "icon", the control will display only items that include the word "icon" in their content. If you clear the filter by setting it to null or an empty string, all items will be shown again. The onfilter event notifies your application when the user applies or clears filters, such as by typing into the control's filter input, allowing you to respond to changes in the filtering criteria. The allowFilterInput field specifies whether the control displays a filter bar, enabling the user to filter items by typing text. The ShowFilterInput() method displays the filter input field, enabling the user to type keywords for filtering items. The CloseFilterInput() method hides the filter input field and clears any applied filter, showing all items again.

The filter field is mapped to the Filter property, which means that the following statements are equivalent:

oRollist.Options = {filter: "icon"}
oRollist.SetOptions({filter: "icon"})
oRollist.Filter = "icon"
oRollist.SetFilter("icon")

null {null} or "" {string}, clears the fiter if any
"icon" {string}, displays only items that include the word 'icon' in their content

The misc field holds the control's miscellaneous options, as an object of MiscellaneousOptions type. The miscellaneous options include various settings that do not fit into other specific categories but still play a crucial role in customizing the control's behavior and appearance. These options can cover a wide range of functionalities, such as defining the type of HTML element used for items, horizontal or vertical arrangement of items, the vertical ratio for the selected item's position, and more.

The misc field is mapped to the Misc property, which means that the following statements are equivalent:

oRollist.Options = {misc: {hAlign: 1}}
oRollist.SetOptions({misc: {hAlign: 1}})
oRollist.Misc = {hAlign: 1}
oRollist.SetMisc({hAlign: 1})

null {null}, indicates the control's default miscellaneous options
{hAlign: 1} {object}, specifies that the items are arranged horizontally

The select field defines the position of the item that is currently selected (which is always displayed at the center of the control). The select field can accept either a number or a string. If you assign a number, it selects the item based on its position in the Items collection (0-based index). For example, setting select to 0 will select the first item, while setting it to 1 will select the second item. If you assign a string, it selects the item based on its identifier or key. For instance, if you have an item with an identifier of "itemId", setting select to "itemId" will select that specific item. The onselect event notifies your application once the user selects an item at runtime (clicks an item).

The select field is mapped to the Select property, which means that the following statements are equivalent:

oRollist.Options = {select: 0}
oRollist.SetOptions({select: 0})
oRollist.Select = 0
oRollist.SetSelect(0)

0 {number} or null {null}, selects the first item based on its position in the Items collection (0-based)
"itemId" {string}, selects the item based on its identifier/key

The smooth field defines the time in ms the control goes from one layout to another. Setting the smooth field to 0 means that no smooth changes are performed once the control goes from a layout to another. Setting the smooth field to 125 means that a smooth-transition is performed from a layout to another for 125 ms. The Smooth() method smoothly transitions the control from the current layout to a new layout, applying gradual changes rather than an immediate switch.

The smooth field is mapped to the Smooth property, which means that the following statements are equivalent:

oRollist.Options = {smooth: 125}
oRollist.SetOptions({smooth: 125})
oRollist.Smooth = 125
oRollist.SetSmooth(125)

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.

The wheelChange field specifies how much the control scrolls when the user rotates 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.

The wheelChange field is mapped to the WheelChange property, which means that the following statements are equivalent:

oRollist.Options = {wheelChange: 5}
oRollist.SetOptions({wheelChange: 5})
oRollist.WheelChange = 5
oRollist.SetWheelChange(5)

0 {number}, locks any action the mouse's wheel performs
1 {number}, scrolls the control by 1-item when mouse's wheel is rotated