Class: List

Constructor

new List(itemsopt)

ComboBox constructor. Accepts an optional Array parameter: strings ["Item 1","Item 2", ...], numbers [1, 2, 3, ...] item objects [{text:"Item 1"}, {text:"Item 2"}, ...], or a mix of them.

Parameters:

Name	Type	Attributes	Description
`items`	Array.<(string\|number\|Object)>	<optional>	Items as an Array of objects, strings or numbers. Can be a mix of these types. For item Object's format check out add() method example .

Example

// Item Object format (All fields other than "text" are optional):
{
    text: string,           // Item text (Required)
    [id]: string|number,    // Value that can be used by software logic to identify this item
    [value]: string|number, // Additional value to be stored in the item for later use.
    [icon]: string,         // Absolute or relative path to icon image, base64 encoded image string, or `null` to remove icon.
    [color]: string,        // Item text color as a 6 character hex encoded color string (e.g. #665500)
    [background]: string,   // Item background color as a 6 character hex encoded color string (e.g. #665500)
    [tooltip]: string,      // Tooltip text to show when pointer hover the item. (in List and Tree components only)
    [font]: font object     // Object{name: string, size: number, bold: boolean, ...}. See complete list of font properties in example of font() method.
}

Classes

List

Members

(readonly) Layout :number

Layouts that can be used to display list items.

Type:

number

Properties

Name	Type	Description
`Vertical`	number	Items are arranged in a single vertical column.
`VerticalWrap`	number	Items flow vertically and wrap into additional columns if needed.
`HorizontalWrap`	number	Items flow horizontally and wrap into additional rows if needed.

Example

list.layout(List.Layout.VerticalWrap);

(readonly) length :number

Gets the amount of items in the list.

Type:

number

(readonly) selectedItems :Array.<Object>

Gets an Array of selected items. Returns selected items as an Array of objects, or empty Array if no item is selected.

Type:

Array.<Object>

Methods

add(item, index) → {List}

Adds a list item at the end of the list, or inserts the item at specified index.

Parameters:

Name	Type	Description
`item`	string \| number \| Object	List item as a String, number, or Object. See item Object format in class example above.
`index`	number	Integer position at which to add the item.

Returns:

Returns this component instance.

Type:: List

Example

combo1.add({text: "New Item", ...more optional properties}); // Adding item as object
combo1.add("New Item"); // Adding item as string
combo1.add(45); // Adding item as number

alignment(alignmentopt) → {string|List}

Sets or gets an alignment of item's label and icon within a list item.

Parameters:

Name	Type	Attributes	Description
`alignment`	string	<optional>	One or combination of alignment describing strings: top, bottom, left, right, and center. Maximum one horizontal and maximum one vertical alignment is allowed.

Returns:

Returns this component instance if at least one argument is provided, otherwise returns the current layout.

Type:: string | List

Example

list.alignment("top left");   // positions label at the top left corner of list item
list.alignment("bottom");     // positions label at the bottom-center of list item
list.alignment("top center"); // positions label at the top-center of list item
list.alignment("center");     // positions label at the center vertically and horizontally

clear() → {List}

Removes all items from the list.

Returns:

Returns an instance of ths List.

Type:: List

findByID(value) → {number}

Finds first item whose ID matches the argument. If item is {text: "First Item", value: "item1", id: 1}, it should be found by passing value 1.

Parameters:

Name	Type	Description
`value`	string \| number	Search by this text or number

Returns:

Returns an index of the first found list items or -1 if no item was found.

Type:: number

findByText(value) → {number}

Finds first item whose text matches the argument. If item is {text: "First Item", value: "item1"}, it should be found by passing value "First Item".

Parameters:

Name	Type	Description
`value`	string	Search by this text

Returns:

Returns an index of the first found list items or -1 if no item was found.

Type:: number

findByValue(value) → {number}

Finds first item whose value matches the argument. If item is {text: "First Item", value: "item1", id: 1}, it should be found by passing value "item1".

Parameters:

Name	Type	Description
`value`	string \| number	Search by this text or number

Returns:

Returns an index of the first found list items or -1 if no item was found.

Type:: number

indexOf(text) → {number}

Returns and index of an item whose text matches provided text.

Parameters:

Name	Type	Description
`text`	string	Text string to find

Returns:

Returns index of a found item or -1.

Type:: number

item(index, itemopt, updateopt) → {List|object}

Gets, sets or updates an item at a specified index. Check usage examples below.

Parameters:

Name	Type	Attributes	Default	Description
`index`	number			Index of the list item
`item`	Object	<optional>		Item object. See object format in the example of ComboBox.add() documentation.
`update`	boolean	<optional>	false	`true` to update specified item properties with provided item properties, `false` to replace the item with new one. Default is `false`.

Returns:

If item argument is passed, then this List instance is returned, otherwise item at specified index is returned. If index is out of range, undefined is returned.

Type:: List | object

Example

const item = list.item(3); // gets the item at index 3
list.item(3, {text: "New text", value:"new value"}); // replaces item at index 3
list.item(3, {background: "#FF7777"}, true); // changes item's background color at index 3

itemPadding(paddingopt) → {string|List}

Gets or sets a padding for each item in the list. See example below.

Parameters:

Name	Type	Attributes	Description
`padding`	number \| string	<optional>	Number for same padding on all sides, string to specify padding for each side "top right bottom left"

Returns:

Returns this component instance if at least one argument is provided, otherwise returns current padding.

Type:: string | List

Example

list.itemPadding(3);                // defines same padding for top, right, bottom and left.
list.itemPadding("5 0 5 3");        // defines padding for each side separately, top=5, right=0, bottom=5 and left=3.
const padding = list.itemPadding(); // gets the padding object

itemSize(width_or_bothopt, heightopt) → {object|List}

Sets the size of each item in the list.

Parameters:

Name	Type	Attributes	Description
`width_or_both`	number \| object	<optional>	Width of items as a number, same width and height as a number, or size Object to set both width and height (see examples below).
`height`	number	<optional>	Height of items.

Returns:

Returns this component instance if at least one argument is provided, otherwise returns the current item size.

Type:: object | List

Example

itemSize(null) - Resets item size to default (auto size).
itemSize(100) - Both width and height are set to 100px.
itemSize(100, 150) - width 100, height 150
itemSize({width:100, height:150})
itemSize() - retrieves size and returns {width:number, height:number} or NULL if it was not previously set.

items(itemsopt) → {List|Array.<object>}

Sets or gets items of the list.

Parameters:

Name	Type	Attributes	Description
`items`	Array.<(object\|string\|number)>	<optional>	Array of items as objects or strings

Returns:

If items are passed, returns an instance of this List, otherwise returns an Object Array of items.

Type:: List | Array.<object>

Example

list.items([{value:1, text:"Label 1", ...}, [{value:2, text:"Label 2", ...}); // Sets items by an array of objects
list.items(["Label 1", "Label 2", ...]); // Sets items by an array of strings
list.items(["Label 1", {value:1, text:"Label 1", ...}, 45); // Sets items as an array of strings, objects and numbers

layout(layoutopt) → {List.Layout|List}

Sets or get layout of the list (Vertical, Horizontal Wrap, or Vertical Wrap). Default is Vertical.

Parameters:

Name	Type	Attributes	Description
`layout`	List.Layout	<optional>	List.Layout.[Vertical\|HorizontalWrap\|VerticalWrap]

Returns:

Returns this component instance if argument is provided, otherwise returns the current layout.

Type:: List.Layout | List

remove(indexopt, deleteCountopt) → {List}

If index argument is specified, N amount of items starting form specified index will be removed. If called without parameters, this component will be removed from it's parent. See examples below.

Parameters:

Name	Type	Attributes	Default	Description
`index`	number	<optional>		Index of the item to remove. If not provided, the component will be removed from its parent.
`deleteCount`	number	<optional>	1	Amount of items to remove

Returns:

Returns this ComboBox instance.

Type:: List

Example

list.remove(); // removes the component from it's parent container
list.remove(4); // removes list item at index 4
list.remove(4, 3); // removes 3 items starting at index 4

rightClickSelect(enableopt) → {boolean|List}

Sets or gets whether to allow selecting list items with a click of a right mouse button.

Parameters:

Name	Type	Attributes	Description
`enable`	boolean	<optional>	Boolean value that enables or disables right-click item selection.

Returns:

Returns this component instance if at least one argument is provided, otherwise returns current value.

Type:: boolean | List

selectAll(selectedopt) → {List}

Selects/Deselects all rows in the Table

Parameters:

Name	Type	Attributes	Default	Description
`selected`	boolean	<optional>	true	`true` to select all rows, `false` to deselect all rows.

Returns:

Returns an instance of this List for method chaining.

Type:: List

selectedIndex(indexopt) → {List|number}

Sets or gets an index of a selected item. Can be used to make one item at certain index to be selected. To select more than one item make sure to enable multi-selection by selectionMode(SelectionMode.Multiple), and then use selection() method instead.

Parameters:

Name	Type	Attributes	Description
`index`	number	<optional>	Index of an item to select.

Returns:

If index is specified, then this component instance is returned, otherwise currently selected index is returned.

Type:: List | number

selection(indicesopt) → {List|Array}

Sets selected indexes of elements in the list or returns an array of selected indexes.

Parameters:

Name	Type	Attributes	Description
`indices`	Array.<number> \| number \| null	<optional>	Array of indexes to be selected, one index number, `null` or -1 to deselect all items

Returns:

When setting, this component instance is returned, otherwise an array indexes of selected items is returned.

Type:: List | Array

selectionMode(mode) → {SelectionMode|List}

Sets or returns a selection mode, which defines how list items can be selected (only one item, multiple items together as a range, or any combination of items).

Parameters:

Name	Type	Description
`mode`	SelectionMode	One of: SelectionMode.Single, SelectionMode.Multiple, SelectionMode.Range. See SelectionMode.

See: SelectionMode

Returns:

Type:: SelectionMode | List