swing-ui 0.1.25 → 1.0.3

package/classes/List.js

@@ -0,0 +1,452 @@
+
+import {ScrollableComponent} from "./ScrollableComponent.js";
+
+/**
+ * List UI component, extends ScrollableComponent class, which extends UIComponent class.
+ * List can be a list of text items, icons, or icons and text. List direction can be vertical, horizontal with wrapping, and vertical with wrapping.
+ * Check example below to become familiar with how the item Object is formatted.
+ *
+ * For more methods for this component check UIComponent class.
+ * @class
+ * @global
+ * @see ScrollableComponent
+ * @see ListItem
+ * @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.
+ * }
+ */
+export class List extends ScrollableComponent
+{
+	/**
+	 * Layouts that can be used to display list items.
+	 * @readonly
+	 * @enum {number}
+	 * @property {number} Vertical - Items are arranged in a single vertical column.
+	 * @property {number} VerticalWrap - Items flow vertically and wrap into additional columns if needed.
+	 * @property {number} HorizontalWrap - Items flow horizontally and wrap into additional rows if needed.
+	 * @example
+	 * list.layout(List.Layout.VerticalWrap);
+	 */
+	static Layout = Object.freeze({Vertical: 0, VerticalWrap: 1, HorizontalWrap: 2});
+	
+	/**
+	 * List constructor.
+	 * Accepts an optional Array parameter: strings ["Item 1","Item 2", ...], numbers [1, 2, 3, ...], and ListItem formatted objects [{text:"Item 1"}, {text:"Item 2"}, ...], or a mix of them.
+	 *
+	 * @param {Array<string|number|ListItem>} [items] - Items as an Array of ListItem formatted objects, strings or numbers. Can be a mix of these types.
+	 * @example
+	 * // Creating combo box, then adding each item separately.
+	 * const combo1 = new ComboBox().add("Item 1").add(45).add({text: "Item 2", font:{bolt:true}});
+	 *
+	 * // Creating combo box, then adding items as an array.
+	 * const combo2 = new ComboBox().items([
+	 *     "Item 1",
+	 *     45,
+	 *     {text: "Item 2", font:{bolt:true}}
+	 * ]);
+	 *
+	 * // Creating combo box with items as a string and object. Items can be a mix of strings and objects.
+	 * const combo3 = new ComboBox([
+	 *      "Item 1",
+	 *      45,
+	 *      {text: "Item 2", font:{bolt:true}}
+	 * ]);
+	 */
+	constructor(...args)
+	{
+		if(args.length > 0)
+		{
+			super("List", (new.target === List), args[0]);
+		}
+		else
+		{
+			super("List", (new.target === List));
+		}
+		
+		this.finalize(List);
+	}
+	
+	/**
+	 * Adds a list item at the end of the list, or inserts the item at specified index.
+	 *
+	 * @param {string|number|ListItem} item - List item as a string, number, or ListItem formatted object.
+	 * @param {number} index - Integer position at which to add the item.
+	 * @returns {number} Returns an index at which the item was inserted, or -1 if item was not inserted for some reason.
+	 * @see ListItem
+	 * @example
+	 * const i = combo1.add({text: "New Item", ...more optional properties}); // Adding item as object
+	 * const i = combo1.add("New Item"); // Adding item as string
+	 * const i = combo1.add(45); // Adding item as number
+	 */
+	add(item, index = -1)
+	{
+		if(item == null) throw new Error(`item is ${typeof item} in List.add(item)`);
+		if(index > -1) item.index = index;
+		return ui.sendToGUI({control: this.id, get: "add", data: item}, r => r.value);
+	}
+	
+	/**
+	 * 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.
+	 *
+	 * @param {number} [index=undefined] - Index of the item to remove. If not provided, the component will be removed from its parent.
+	 * @param {number} [deleteCount=1] - Amount of items to remove
+	 * @returns {List} Returns `this` ComboBox instance.
+	 * @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
+	 */
+	remove()
+	{
+		let value = null;
+		
+		if(arguments.length > 0 && typeof arguments[0] !== "boolean")
+		{
+			value = parseInt(arguments[0]);
+			if(isNaN(value) || value < 0) return this; // if not valid index, return now
+			let qty = arguments.length > 1 && !isNaN(arguments[1]) ? parseInt(arguments[1]) : 1;
+			
+			ui.sendToGUI({control: this.id, set: "remove", value: value, qty: qty});
+			return this;
+		}
+		else
+		{
+			return super.remove();
+		}
+	}
+	
+	/**
+	 * Gets the amount of items in the list.
+	 * @readonly
+	 * @type {number}
+	 */
+	get length()
+	{
+		return ui.sendToGUI({control: this.id, get: "length"});
+	}
+	
+	/**
+	 * Gets, sets or updates an item at a specified index. Check usage examples below.
+	 *
+	 * @param {number} index - Index of the list item
+	 * @param {ListItem} [item] - Item object. See object format in the example of ComboBox.add() documentation.
+	 * @param {boolean} [update=false] - `true` to update specified item properties with provided item properties, `false` to replace the item with new one. Default is `false`.
+	 * @returns {List|ListItem} 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.
+	 * @see ListItem
+	 * @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
+	 */
+	item(i)
+	{
+		if(typeof i !== "number") i = parseInt(i);
+		if(!Number.isSafeInteger(i) || i < 0) throw new Error(`Invalid "index" argument passed to List.item(i). A positive number is expected, but received a ${typeof arguments[0]}: ${arguments[0]}.`);
+		
+		if(arguments.length > 1)
+		{
+			if(typeof arguments[1] !== "object") arguments[1] = {text: String(arguments[1]), id: arguments[1]}; // create object
+			arguments[1].index = i;
+			arguments[1].update = (arguments.length > 2 && arguments[2] === true);
+			ui.sendToGUI({control: this.id, set: "item", value: arguments[1]});
+			return this;
+		}
+		else
+		{
+			return ui.sendToGUI({control: this.id, get: "item", data: parseInt(i)});
+		}
+	}
+	
+	/**
+	 * Sets selected indexes of elements in the list or returns an array of selected indexes.
+	 *
+	 * @param {number[]|number|null} [indices] - Array of indexes to be selected, one index number, `null` or -1 to deselect all items
+	 * @returns {List|Array} When setting, `this` component instance is returned, otherwise an array indexes of selected items is returned.
+	 */
+	selection()
+	{
+		if(arguments.length > 0)
+		{
+			var arg1 = arguments[0];
+			
+			ui.sendToGUI({control: this.id, set: "selection", value: Array.isArray(arg1) ? arg1 : ((arg1 === -1 || arg1 == null || arg1 === false) ? [] : [parseInt(arg1)])});
+			return this;
+		}
+		else
+		{
+			let _i = ui.sendToGUI({control: this.id, get: "selection"});
+			return (_i !== null && _i.length !== undefined) ? _i : [];
+		}
+	}
+	
+	/**
+	 * Gets an Array of selected items. Returns selected items as an Array of objects, or empty Array if no item is selected.
+	 *
+	 * @readonly
+	 * @type {ListItem[]}
+	 */
+	get selectedItems()
+	{
+		return this.property("selectedItems", arguments) ?? []; // if return value is NULL, then return empty array
+	}
+	
+	/**
+	 * 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.
+	 *
+	 * @param {number} [index] - Index of an item to select.
+	 * @returns {List|number} If index is specified, then `this` component instance is returned, otherwise currently selected index is returned.
+	 */
+	selectedIndex()
+	{
+		if(arguments.length > 0)
+		{
+			return this.selection(parseInt(arguments[0]));
+		}
+		else
+		{
+			let _i = this.selection();
+			return _i.length > 0 ? _i[0] : -1;
+		}
+	}
+	
+	/**
+	 * 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).
+	 *
+	 * @param {SelectionMode} mode - One of: SelectionMode.Single, SelectionMode.Multiple, SelectionMode.Range. See {@link SelectionMode}.
+	 * @returns {SelectionMode|List}
+	 * @see SelectionMode
+	 */
+	selectionMode()
+	{
+		if(arguments.length > 0) arguments[0] = String(arguments[0]);
+		return this.property("selectionMode", arguments);
+	}
+	
+	/**
+	 * Selects/Deselects all items in the List
+	 *
+	 * @param {boolean} [selected=true] - `true` to select all items, `false` to deselect.
+	 * @return {List} Returns an instance of `this` List for method chaining.
+	 */
+	selectAll(selected = true)
+	{
+		this.property("selectAll", [selected === true]);
+		return this;
+	}
+	
+	/**
+	 * Sets or gets items of the list.
+	 * @arg {Array.<(object|string|number)>} [items] - Array of items as objects or strings
+	 * @returns {List|object[]} If items are passed, returns an instance of `this` List, otherwise returns an Object Array of items.
+	 * @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
+	 */
+	items()
+	{
+		if(arguments.length > 0)
+		{
+			ui.sendToGUI({control: this.id, set: "items", value: arguments[0]});
+			return this;
+		}
+		else
+		{
+			return ui.sendToGUI({control: this.id, get: "items"}) ?? [];
+		}
+	}
+	
+	/**
+	 * Removes all items from the list.
+	 * @returns {List} Returns an instance of ths List.
+	 */
+	clear()
+	{
+		ui.sendToGUI({control: this.id, set: "clear"});
+		return this;
+	}
+	
+	/**
+	 * Sets or get layout of the list (Vertical, Horizontal Wrap, or Vertical Wrap).
+	 * Default is Vertical.
+	 *
+	 * @param {List.Layout} [layout] - List.Layout.[Vertical|HorizontalWrap|VerticalWrap]
+	 * @return {List.Layout|List} Returns `this` component instance if argument is provided, otherwise returns the current layout.
+	 */
+	layout(...args)
+	{
+		if(args.length > 0) args[0] = parseInt(args[0]);
+		return this.property("layout", args);
+	}
+	
+	/**
+	 * Sets the size of each item in the list.
+	 *
+	 * @param {number|object} [width_or_both] - 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).
+	 * @param {number} [height] - Height of items.
+	 * @return {object|List} Returns `this` component instance if at least one argument is provided, otherwise returns the current item size.
+	 * @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.
+	 */
+	itemSize()
+	{
+		let _a = arguments;
+		
+		if(_a.length === 0)
+		{
+			return this.property("itemSize", []);
+		}
+		else if(_a.length === 1)
+		{
+			if(_a[0] === null)
+			{
+				_a[0] = [-1, -1];
+			}
+			else if(typeof _a[0] === "object")
+			{
+				if(_a[0].width !== undefined && _a[0].height !== undefined)
+				{
+					_a[0] = [parseInt(_a[0].width), parseInt(_a[0].height)];
+				}
+				else
+				{
+					_a[0] = null;
+				}
+			}
+			else
+			{
+				_a[0] = [parseInt(_a[0]), parseInt(_a[0])];
+			}
+		}
+		else if(_a.length > 1)
+		{
+			_a[0] = [parseInt(_a[0]), parseInt(_a[1])];
+		}
+		
+		return this.property("itemSize", [_a[0]]);
+	}
+	
+	/**
+	 * Sets or gets an alignment of item's label and icon within a list item.
+	 *
+	 * @param {string} [alignment] - One or combination of alignment describing strings: top, bottom, left, right, and center. Maximum one horizontal and maximum one vertical alignment is allowed.
+	 * @return {string|List} Returns `this` component instance if at least one argument is provided, otherwise returns the current layout.
+	 * @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
+	 */
+	alignment()
+	{
+		return this.property("alignment", arguments);
+	}
+	
+	/**
+	 * Gets or sets a padding for each item in the list. See example below.
+	 *
+	 * @param {number|string} [padding] - Number for same padding on all sides, string to specify padding for each side "top right bottom left"
+	 * @return {string|List} Returns `this` component instance if at least one argument is provided, otherwise returns current padding.
+	 * @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
+	 */
+	itemPadding(...args)
+	{
+		if(args.length === 0)
+		{
+			const padding = this.property("itemPadding", []);
+			return `${padding.top ?? 0} ${padding.right ?? 0} ${padding.bottom ?? 0} ${padding.left ?? 0}`;
+		}
+		else
+		{
+			let padding;
+			
+			if(typeof args[0] === "string")
+			{
+				const nums = args[0].match(/\d+/g)?.map(Number).slice(0, 4) || [];
+				padding = {top: nums[0] ?? 0, right: nums[1] ?? 0, bottom: nums[2] ?? 0, left: nums[3] ?? 0};
+			}
+			else
+			{
+				args[0] = parseInt(args[0]);
+				padding = {top: args[0], right: args[0], bottom: args[0], left: args[0]};
+			}
+			
+			return this.property("itemPadding", [padding]);
+		}
+	}
+	
+	/**
+	 * Sets or gets whether to allow selecting list items with a click of a right mouse button.
+	 * @param {boolean} [enable] - Boolean value that enables or disables right-click item selection.
+	 * @return {boolean|List} Returns `this` component instance if at least one argument is provided, otherwise returns current value.
+	 */
+	rightClickSelect(...args)
+	{
+		if(args.length > 0) args[0] = (args[0] === true); // ensure boolean
+		return this.property("rightClickSelect", arguments);
+	}
+	
+	/**
+	 * Finds items whose text matches the string argument. If item is {text: "First Item", value: "item1"}, it should be found by passing value "First Item".
+	 *
+	 * @param {string} value - Search by this text
+	 * @return {ListItem[]} Returns an array of found items. Each found item will have an `index` property fo convenience.
+	 */
+	findByText(value)
+	{
+		return ui.sendToGUI({control: this.id, get: "findBy", data: {by: "text", q: value}});
+	}
+	
+	/**
+	 * 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".
+	 *
+	 * @param {string|number} value - Search by this text or number
+	 * @return {ListItem[]} Returns an array of found items. Each found item will have an `index` property fo convenience.
+	 */
+	findByValue(value)
+	{
+		return ui.sendToGUI({control: this.id, get: "findBy", data: {by: "value", q: value}});
+	}
+	
+	/**
+	 * 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.
+	 *
+	 * @param {string|number} value - Search by this text or number
+	 * @return {ListItem[]} Returns an array of found items. Each found item will have an `index` property fo convenience.
+	 */
+	findByID(value)
+	{
+		return ui.sendToGUI({control: this.id, get: "findBy", data: {by: "id", q: value}});
+	}
+	
+	/**
+	 * Scrolls the scroll bars to make sure the item at specified index is visible. If position is specified, the item will be placed at the specified position between the top and bottom of the List component.
+	 *
+	 * @param {number} index - Index of a list item to make visible.
+	 * @param {number} [position] - A decimal number between 0 and 1 indicating vertical position in percentages (0% - 100% of the height of the component). If omitted, the item will only become visible, but not at a specific location.
+	 */
+	scrollToIndex(index = 0, position = undefined)
+	{
+		if(typeof index !== "number") throw new Error(`List.scrollToIndex(index) expects a number as a first argument, but ${typeof index} is received.`);
+		return this.property("scrollToIndex", [{index: index, position: position}]);
+	}
+}