Class: ComboBox

Constructor

new ComboBox(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 mixture of them.

Parameters:

Name	Type	Attributes	Description
`items`	Array.<(string\|number\|ListItem)>	<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 .

See: ListItem

Example

// ListItem object format:
ListItem {
    text: string,         // Item text (required only for a new item).
    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{name: string, size: number, bold: boolean, ...}. See complete list of font properties in example of font() method.
}

Classes

ComboBox

Members

(readonly) length :number

Gets the amount of items in the list.

Type:

number

(readonly) selectedItem :ListItem|null

Gets a selected item. Returns a selected item as an Object, or undefined if no item is selected.

Type:

ListItem | null

Methods

add(item, index) → {ComboBox}

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

Parameters:

Name	Type	Description
`item`	string \| number \| ListItem	List item as a string, number or a ListItem formatted object.
`index`	number	Integer position at which to add the item.

See: ListItem

Returns:

Returns this component instance.

Type:: ComboBox

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

clear() → {ComboBox}

Removes all items.

Returns:

Returns this component instance.

Type:: ComboBox

indexOf(text) → {number}

Returns and index of a first 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) → {ComboBox|ListItem}

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`	ListItem	<optional>		ListItem formatted object. See ListItem 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`.

See: ListItem

Returns:

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

Type:: ComboBox | ListItem

Example

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

itemPadding(padding) → {string|List}

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

Parameters:

Name	Type	Description
`padding`	number \| string	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

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

items(itemsopt) → {ComboBox|Array.<(string|number|ListItem)>}

Sets or gets an array of list items. When setting, all existing items in the list will be removed before new ones are added.

Parameters:

Name	Type	Attributes	Description
`items`	Array.<(string\|number\|ListItem)>	<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 .

Returns:

When getting, an Array is returned, otherwise this component instance is returned.

Type:: ComboBox | Array.<(string|number|ListItem)>

onPopupEvents(callbackopt, removeopt) → {Array.<function()>|ComboBox}

Registers, unregisters and gets a list of handler functions for the popup list events (when the popup becomes visible and hidden).

Parameters:

Name	Type	Attributes	Description
`callback`	function	<optional>	Handler function receiving PopupEvent object. Pass `null` to unregister all handler callbacks.
`remove`	boolean	<optional>	Set to `true` to unregister the handler function.

See: PopupEvent

Returns:

Returns an array of registered handler functions if arguments are omitted, otherwise returns this component instance.

Type:: Array.<function()> | ComboBox

Example

// event Object format:
const e = {
  target: object,        // The component that triggered the event.
  type: string,          // `show`, `hide`, `cancel`.
  x: number,             // Component's X position
  y: number,             // Component's Y position
  interactive: boolean,  // Indicates if the popup was triggered by user's interaction (not programmatically).
};

open(visibleopt) → {ComboBox|boolean}

Shows or hides the popup list, or get a boolean whether the popup is visible.

Parameters:

Name	Type	Attributes	Description
`visible`	bool	<optional>	`true` to show, `false` to hide.

Returns:

Returns this component instance if argument is passed, otherwise returns boolean value indication if the popup list is currently visible.

Type:: ComboBox | boolean

popupSize(size) → {ComboBox|number}

Sets or gets the maximum number of items to show in a popup list without having to scroll.

Parameters:

Name	Type	Description
`size`	number	Defines the maximum amount of items that should be visible in the popup list without having to scroll.

Returns:

Returns number value if argument is omitted, otherwise returns this component instance.

Type:: ComboBox | number

remove(indexopt) → {ComboBox}

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	Description
`index`	number	<optional>	Index of the item to remove. If not provided, the component will be removed from its parent.

Returns:

Returns this ComboBox instance for method chaining.

Type:: ComboBox

Example

combo.remove(); // removes the component from it's parent container
combo1.remove(4); // removes list item at index 4

selectedID(idopt) → {ComboBox|number|string|null}

Selects a first item whose id property matches provided id, or gets an id property of currently selected item.

Parameters:

Name	Type	Attributes	Description
`id`	string \| number	<optional>	ID of an item to be selected.

Returns:

If id parameter is specified, then this ComboBox instance is returned, otherwise an id of selected item is returned, or null if no item is selected.

Type:: ComboBox | number | string | null

selectedIndex(indexopt) → {ComboBox|number}

Sets or gets an index of a selected item. Can be used to make an item at certain index to be selected.

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:: ComboBox | number

selectedValue(valueopt) → {ComboBox|number|string|null}

Selects and item that has a specified value, or gets a value of currently selected item.

Parameters:

Name	Type	Attributes	Description
`value`	string \| number	<optional>	Value of an item to be selected.

Returns:

If a value is specified, then this ComboBox instance is returned, otherwise a value of selected item is returned, or null if no item is selected.

Type:: ComboBox | number | string | null