Item class (Rollist)

Item(oItems, oItemOpts)

new Item(oItems, oItemOpts)

The Item object holds the item of the control. The Item(id) method returns the item based on its index or identifier/key.

Every option of the ItemOptions type has associated a property of the Item object. For instance, the option:

value {string}, defines the value for individual item
is associated with the property:
Value {any}, defines the value for individual item
which means that the following statements are equivalent:
oItem.Options = {value: 100}
oItem.SetOptions({value: 100})
oItem.Value = 100
oItem.SetValue(100)
where oItem is an object of Item type
Parameters:
Name Type Description
oItems Item Indicates an object of Items type that's the owner collection of this item.
oItemOpts ItemOptions Specifies the options to apply on the item.

Members

ClassName :string

The ClassName property defines an additional class name to apply to the HTML element that hosts the item. By default, the 'exrolitem' class is applied to the element. If you want to apply custom styles to specific items, you can use the ClassName property to add an extra class name to the item's hosting element. This allows you to define CSS rules for that class and style the item accordingly. For example, if you set ClassName to "red", the HTML element for that item will have both 'exrolitem' and 'red' as its class names, enabling the styles defined in the .red CSS class to affect that item. By default, the ClassName property is null, meaning no extra class name is applied and only 'exrolitem' is used for styling.
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

(readonly) Index :number

The Index property retrieves the item's current index. The item's index is a zero-based number representing its position within the Items collection. It can be used to access the item via the Rollist.Item() method. Because the index of an item may change when items are added or removed, it is recommended to use the GetIndex() method to obtain the current index whenever needed. Note that the Index refers to the item's position within the Items collection, while the Position property refers to the item's position among the visible items.
Type:
  • number
Example
The following statements are equivalents:

 oItem.GetIndex(), retrieves the item's index
 oItem.Index, retrieves the item's index

where oItem is an object of Item type
Index

Key :string

The Key property defines the key of the item. The Rollist.Item() method allows you to get an item either by its key or by its index. By default, the Key property is null, meaning no key is assigned and the item's index must be used to access it. The Key property provides a convenient way to identify and access items without relying on their index, which can change when items are added or removed from the collection.
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

Options :ItemOptions

The Options property defines the item's options (visibility, caption, ...) at once. The options include visibility, caption, and so on. The Options property of the item customizes the item's appearance and behavior.

Every option of the ItemOptions type has associated a property of the Item object. For instance, the option:

value {string}, defines the value for individual item
is associated with the property:
Value {any}, defines the value for individual item
which means that the following statements are equivalent:
oItem.SetOptions({value: 100}), changes the value of the item to 100 oItem.Value = 100, changes the value of the item to 100
where oItem is an object of Item type

It is important to note that changing a field of the ItemOptions object does not automatically update the item. For example, oItem.Options.value = 100 does not apply the change. Instead, you must assign the Options property again, such as oItem.Options = {value: 100}, so the item updates and applies the new value.

Type:
Example
oItem.Options = {shape: "red", height: 32}, changes the item's height and background
oItem.SetOptions({shape: "red", height: 32}), changes the item's height and background
Options

Position :number

The Position property defines the item's position. It can be set to a positive number to indicate the zero-based index of the item within the control, or set to null to add the item at the end of the list. By default, the Position property is null, meaning the item is added at the end of the list. The Visible property indicates whether the item is visible or hidden.
Type:
  • number
Example
0 {number}, moves the item to the first position within the control
1 {number}, moves the item to the second position within the control
Position

Value :string

The Value property defines the label of an item. The label can be a simple string or complex HTML content. You can use the ClassName property to apply CSS styles to the item, and combine it with HTML tags in the Value property to structure and enhance the visual appearance of the content. For example, you can use tags such as <b> for bold text or <font color='red'> for colored text. By using HTML within the Value property, you can fully customize the item's label to match your application's design and improve the user experience.

Please note that modifying an item's value does not automatically refresh the control. The changes are applied only after calling the Refresh() method.

Type:
  • string
Example
null {null}, resets the caption of the item
"caption" {string}, defines the plain-caption for the item
"&lt;font color='red'&gt;caption&lt;/font&gt;" {string}, defines an item that shows the "caption" text in red color
"&lt;li&gt;caption&lt;/li&gt;" {string}, defines an item that shows the "caption" text as a list item
"&lt;img src="exontrol.png"&gt;Exontrol" {string}, defines a caption with an image for the item
Value

Visible :boolean

The Visible property shows or hides the item. Setting Visible to true shows the item, while setting it to false hides it. The Position field specifies the item's position within its container or collection. By default, Visible is set to true, meaning that items are displayed unless explicitly hidden.
Type:
  • boolean
Example
false {boolean}, hides the item
true {boolean}, shows the item
Visible

Methods

Remove()

The Remove() method removes the item itself from the items collection. The Items.Remove(id) method of Items collection is equivalent with this method. The Remove method allows for the removal of specific items based on their index, identifier/key, or reference. The Clear() method can be used to remove all items from the control, providing a way to reset the item collection before adding new items. The Item() method retrieves a specific item based on its index, identifier/key, or reference. The Count property returns the total number of items currently in the collection. To add a new item to the control, use the Add() method, which creates and adds a new item based on the provided options. The onremoveitem event occurs once an item has been removed from the Items collection.
Example
The following statements are equivalent:

 oRollist.Item("caption").Remove(), removes the item with the specified caption
 oRollist.Item.Remove("caption"), removes the item with the specified caption

where oRollist is an object of Rollist type.
Remove