swing-ui 0.1.25 → 1.0.1

package/classes/Arc.js

@@ -0,0 +1,185 @@
+
+import {Shape} from "./Shape.js";
+
+/**
+ * An `Arc` shape that extends the {@link Shape} class.
+ *
+ * An Arc is a portion of a circle defined by its center coordinates, width (horizontal diameter), height (vertical diameter), starting angle, and extent (the angular span of the arc) in degrees.
+ *
+ * @class
+ * @global
+ * @see Shape
+ */
+export class Arc extends Shape
+{
+	/**
+	 * Enum for arc drawing types: Pie and Chord.
+	 *
+	 * @readonly
+	 * @enum {number}
+	 * @property {number} Chord - Draws the arc as a straight chord between the start and end points.
+	 * @property {number} Pie - Draws the arc as a pie shape (arc connected to the center).
+	 * @example
+	 * Arc.Type.Pie
+	 */
+	static Type = Object.freeze({Chord: 1, Pie: 2});
+	
+	_size = {width: 100, height: 100};
+	_hole_size = {width: 0, height: 0};
+	_start_angle = 0;
+	_extent = 360;
+	_arc_type = Arc.Type.Chord;
+	
+	/**
+	 * Creates an instance of Arc shape.
+	 *
+	 * @param {Stroke} [stroke] - A border of the shape.
+	 * @param {string} [background] - Color, gradient, or image background, similar to CSS. Use an empty string to remove the background.
+	 * @param {number} [opacity] - Opacity of the shape (0 to 1).
+	 * @param {number} [x] - Horizontal position from the left edge.
+	 * @param {number} [y] - Vertical position from the top edge.
+	 * @param {number} [width] - Width of the arc (horizontal diameter).
+	 * @param {number} [height] - Height of the arc (vertical diameter). If omitted, height will be same as width.
+	 * @param {number} [startAngle] - Starting angle of the arc (0 to 360 degrees).
+	 * @param {number} [sweepAngle] - How much the arc is open (0 to 360 degrees).
+	 * @param {Arc.Type} [type] = Arc type. One of: `Arc.Type.Chord`, `Arc.Type.Pie`.
+	 */
+	constructor(stroke = undefined, background = undefined, opacity = 1, x = 0, y = 0, width = 100, height = undefined, startAngle = 0, sweepAngle = 360, type = Arc.Type.Chord)
+	{
+		super(undefined, stroke, background, opacity, x, y);
+		this._type = "arc";
+		this._size = {width: width, height: height != null ? height : width};
+		this._start_angle = startAngle;
+		this._extent = Math.max(0, Math.min(360, parseFloat(sweepAngle)));
+		this._arc_type = Math.max(Arc.Type.Chord, Math.min(Arc.Type.Pie, parseInt(type)));
+	}
+	
+	/**
+	 * Sets or gets the size of the arc (horizontal and vertical diameter).
+	 *
+	 * @param {number|{width:number, height:number}} width - Width of the arc (horizontal diameter), or a size object (e.g., {width:300,height:300}).
+	 * @param {number} [height] - Height of the arc (vertical diameter).
+	 * @returns {{width:number, height:number}|Arc} If called without parameters, current size is returned; otherwise this Arc object is returned.
+	 */
+	size()
+	{
+		if(arguments.length > 0)
+		{
+			this._size = (arguments.length > 1) ? {width: arguments[0], height: arguments[1]} : arguments[0];
+			
+			if(typeof this._size !== "object") this._size = {width: this._size, height: this._size};
+			this.update("min");
+			return this;
+		}
+		else
+		{
+			return {width: this._size.width, height: this._size.height};
+		}
+	}
+	
+	/**
+	 * Sets or gets the size of the hollow space inside the arc. The hole make it look more like a donut.
+	 *
+	 * @param {number|{width:number, height:number}} width - Width of the hole (horizontal diameter), or a size object (e.g., {width:50,height:50}).
+	 * @param {number} [height] - Height of the hole (vertical diameter).
+	 * @returns {{width:number, height:number}|Arc} If called without parameters, current hole size is returned; otherwise this Arc object is returned.
+	 */
+	holeSize()
+	{
+		if(arguments.length > 0)
+		{
+			this._hole_size = (arguments.length > 1) ? {width: arguments[0], height: arguments[1]} : arguments[0];
+			
+			if(typeof this._hole_size !== "object") this._hole_size = {width: this._hole_size, height: this._hole_size};
+			this.update("min");
+			return this;
+		}
+		else
+		{
+			return {width: this._size.width, height: this._size.height};
+		}
+	}
+	
+	/**
+	 * Sets or gets the type of the arc to Arc.Type.Chord or Arc.Type.Pie
+	 *
+	 * @param {Arc.Type} [type] - One of the type values: Arc.Type.Pie, Arc.Type.Chord
+	 * @returns {Arc.Type|Arc} If called without parameters, current type is returned; otherwise this Arc object is returned.
+	 */
+	type()
+	{
+		if(arguments.length > 0)
+		{
+			this._arc_type = arguments[0];
+			
+			this.update("min");
+			return this;
+		}
+		else
+		{
+			return this._arc_type;
+		}
+	}
+	
+	/**
+	 * Gets or sets the starting angle of the arc.
+	 *
+	 * The starting angle defines where the arc begins, measured in degrees
+	 * from the positive x-axis in a clockwise direction.
+	 *
+	 * @param {number} [angle] - Sets the start angle (0 to 360 degrees).
+	 * @returns {number|Arc} Returns the current start angle if no parameter is given, otherwise returns the Arc instance for chaining.
+	 */
+	startAngle()
+	{
+		if(arguments.length > 0)
+		{
+			this._start_angle = parseFloat(arguments[0]) % 360;
+			if(this._start_angle < 0) this._start_angle = 360 + this._start_angle;
+			this.update("min");
+			return this;
+		}
+		
+		return this._start_angle;
+	}
+
+	/**
+	 * Sets or gets how much the arc is open in degrees, between 0 and 360.
+	 *
+	 * @param {number} [sweepAngle] - Sweep angle of the opening starting from the start angle (0 and 360).
+	 * @returns {number|Arc} If called without parameters, current value is returned; otherwise this Arc object is returned.
+	 */
+	sweepAngle()
+	{
+		if(arguments.length > 0)
+		{
+			this._extent = Math.max(0, Math.min(360, parseFloat(arguments[0])));
+			this.update("min");
+			return this;
+		}
+
+		return this._extent;
+	}
+	
+	/**
+	 * Returns a JSON object that contains this shape properties. It may be converted back to this shape.
+	 *
+	 * @param {string} [include="all"] - Specified what to include. "all" is default. Valid values are: "all", "stroke", "background", "points", "basic".
+	 * @return {object} Returns an object containing this shape's properties.
+	 */
+	toObject(include = "all")
+	{
+		let obj = super.toObject(include);
+		
+		if(this._type === "arc")
+		{
+			obj.size = this._size;
+			obj.hole_size = this._hole_size;
+			obj.start_angle = this._start_angle;
+			obj.extent = this._extent;
+			obj.arc_type = this._arc_type;
+		}
+		
+		return obj;
+	}
+}

package/classes/Button.js

@@ -0,0 +1,55 @@
+
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * Button UI component that extends UIComponent class.
+ * For more methods for this component check UIComponent class.
+ * @class
+ * @global
+ */
+export class Button extends UIComponent
+{
+	/**
+	 * Button constructor.
+	 *
+	 * @param {string} [text] - Button text
+	 * @example
+	 * this.button1 = new Button().text("Click Me");
+	 * this.button2 = new Button("Click Me");
+	 */
+	constructor()
+	{
+		super("Button", (new.target === Button), ...arguments);
+		
+		this.finalize(Button);
+	}
+	
+	/**
+	 * Sets or gets an action command. This command is specified in event object for onAction(e => {alert(e.command);}) event handler.
+	 * Default value of action command for a Button is it's initial text.
+	 *
+	 * @param {string} [command] (Optional)
+	 * @return {string|Button} If called without arguments, returns `number` value, otherwise returns `this` Button instance.
+	 * @example
+	 * const button = new Button("Activate").addTo(window).center();
+	 * button.command("Activate Motor 1");
+	 * button.onAction(e => {
+	 *    alert(e.command); // shows a dialog window with a message "Activate Motor 1" when button is clicked.
+	 * });
+	 */
+	command(...args)
+	{
+		if(args.length > 0 && typeof args[0] !== "string") args[0] = String(args[0]); // enforce string type
+		return this.property("actionCommand", args);
+	}
+	
+	/**
+	 * Returns current size of an icon, or `null` when no icon has been set or icon failed to load.
+	 * @readonly
+	 * @type {Size|null}
+	 */
+	get iconSize()
+	{
+		return this.property("iconSize", []);
+	}
+}

package/classes/CheckBox.js

@@ -0,0 +1,33 @@
+
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * Check box UI component that extends UIComponent class.
+ * For more methods for this component check UIComponent class.
+ * @class
+ * @global
+ */
+export class CheckBox extends UIComponent
+{
+	/**
+	 * CheckBox constructor.
+	 *
+	 * @param {string} [text] - Text displayed next to the checkbox
+	 */
+	constructor()
+	{
+		super("CheckBox", (new.target === CheckBox), ...arguments);
+		this.finalize(CheckBox);
+	}
+	
+	/**
+	 * Sets or gets the selection state of the checkbox.
+	 *
+	 * @param {boolean} [selected] - `true` to select, `false` to deselect the checkbox.
+	 * @return {boolean|CheckBox} If called without arguments, returns `boolean` value, otherwise returns `this` CheckBox instance.
+	 */
+	selected()
+	{
+		return this.property("selected", arguments);
+	}
+}

package/classes/CheckBoxMenuItem.js

@@ -0,0 +1,24 @@
+
+import {MenuItem} from "./MenuItem.js";
+
+/**
+ * Check box menu item UI component that extends MenuItem class.
+ * For more methods for this component check MenuItem and UIComponent class.
+ * @class
+ * @global
+ * @see MenuItem
+ * @extends MenuItem
+ */
+export class CheckBoxMenuItem extends MenuItem
+{
+	/**
+	 * Sets or gets boolean indicating whether this component is be selected.
+	 *
+	 * @param {boolean} selected - `true` to select, `false` to deselect.
+	 * @return {CheckBoxMenuItem|boolean} Returns `this` CheckBoxMenuItem instance if argument is provided, otherwise returns `boolean` value.
+	 */
+	selected()
+	{
+		return this.property("selected", arguments);
+	}
+}

package/classes/ComboBox.js

@@ -0,0 +1,329 @@
+
+import {TextComponent} from "./TextComponent.js";
+
+/**
+ * ComboBox UI component that extends UIComponent class.
+ * Check examples below and become familiar with a {@link ListItem} object format.
+ * @class
+ * @global
+ * @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.
+ * }
+ */
+export class ComboBox extends TextComponent
+{
+	/**
+	 * 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.
+	 *
+	 * @param {Array<string|number|ListItem>} [items] - 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
+	 * // 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 3", 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 3", font:{bolt:true}}
+	 * ]);
+	 */
+	constructor(...args) // accepts an optional parameter, array of string for list items
+	{
+		super("ComboBox", (new.target === ComboBox), ...args);
+		this.finalize(ComboBox, TextComponent);
+	}
+	
+	/**
+	 * 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 a {@link ListItem} formatted object.
+	 * @param {number} [index=undefined] - Integer position at which to add the item.
+	 * @returns {number} Returns an index of the added item, or -1 if the item was not added.
+	 * @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 = undefined)
+	{
+		// make sure that value is an object
+		if(typeof item !== "object") item = {id: item, text: String(item)};
+		
+		if(index > -1) item.index = parseInt(index);
+		return ui.sendToGUI({control: this.id, get: "add", data: {item: item, index: index}}, 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.
+	 * @returns {ComboBox} Returns `this` ComboBox instance for method chaining.
+	 * @example
+	 * combo.remove(); // removes the component from it's parent container
+	 * combo1.remove(4); // removes list item at index 4
+	 */
+	remove()
+	{
+		if(arguments.length > 0 && typeof arguments[0] !== "boolean")
+		{
+			// remove item at specified index
+			ui.sendToGUI({control: this.id, set: "removeItem", value: parseInt(arguments[0])});
+			
+			return this;
+		}
+		
+		// remove this element from it's parent (as usual)
+		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] - ListItem formatted object. See {@link ListItem} 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 {ComboBox|ListItem} 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.
+	 * @see 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
+	 */
+	item(index)
+	{
+		if(typeof index !== "number") index = parseInt(i);
+		if(!Number.isSafeInteger(index) || index < 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)
+		{
+			let item = arguments[1];
+			
+			// make sure that value is an object
+			if(typeof item !== "object") item = {id: item, text: String(value)};
+			
+			item.index = index;
+			item.update = (arguments.length > 2 && arguments[2] === true);
+			
+			ui.sendToGUI({control: this.id, set: "item", value: item});
+			return this;
+		}
+		else
+		{
+			return ui.sendToGUI({control: this.id, get: "item", data: parseInt(index)});
+		}
+	}
+	
+	/**
+	 * Gets a selected item. Returns a selected item as a ListItem formatted object, or `null` if no item is selected.
+	 *
+	 * @readonly
+	 * @type {ListItem|null}
+	 */
+	get selectedItem()
+	{
+		return this.property("selectedItem", arguments) ?? null;
+	}
+	
+	/**
+	 * Sets or gets an index of a selected item. Can be used to make an item at certain index to be selected.
+	 *
+	 * @param {number} [index] - Index of an item to select. Set -1 to make no item be selected.
+	 * @returns {ComboBox|number} If index is specified, then `this` component instance is returned, otherwise currently selected index is returned.
+	 */
+	selectedIndex(...args)
+	{
+		if(args.length > 0) args[0] = parseInt(args[0]);
+		return this.property("index", args);
+	}
+	
+	/**
+	 * Selects and item that has a specified value, or gets a value of currently selected item.
+	 *
+	 * @param {string|number|null} [value] - Value of an item to be selected. Set `null` to make no item selected.
+	 * @returns {ComboBox|number|string|null} 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.
+	 */
+	selectedValue(...args)
+	{
+		return this.property("value", args);
+	}
+	
+	/**
+	 * Selects a first item whose `id` property matches provided `id`, or gets an `id` property of currently selected item.
+	 *
+	 * @param {string|number} [id] - ID of an item to be selected.
+	 * @returns {ComboBox|number|string|null} 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.
+	 */
+	selectedID(...args)
+	{
+		return this.property("id", args);
+	}
+	
+	/**
+	 *
+	 * Sets or gets an array of list items. When setting, all existing items in the list will be removed before new ones are added.
+	 *
+	 * @param {Array<string|number|ListItem>} [items] - 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 {ComboBox|Array<ListItem>} When getting, an Array is returned, otherwise `this` component instance is returned.
+	 */
+	items()
+	{
+		return this.property("items", arguments);
+	}
+	
+	/**
+	 * Removes all items.
+	 * @return {ComboBox} Returns `this` component instance.
+	 */
+	clear()
+	{
+		ui.sendToGUI({control: this.id, set: "clear"});
+		return this;
+	}
+	
+	/**
+	 * Shows or hides the popup list, or get a boolean whether the popup is visible.
+	 *
+	 * @param {bool} [visible] - `true` to show, `false` to hide.
+	 * @return {ComboBox|boolean} Returns `this` component instance if argument is passed, otherwise returns `boolean` value indication if the popup list is currently visible.
+	 */
+	open(...args)
+	{
+		if(args.length > 0) args[0] = (args[0] === true); // validate boolean input value
+		return this.property("open", args);
+	}
+	
+	/**
+	 * Registers, unregisters and gets a list of handler functions for the popup list events (when the popup becomes visible and hidden).
+	 *
+	 * @param {function(PopupEvent):any} [callback] - Handler function receiving {@link PopupEvent} object. Pass `null` to unregister all handler callbacks.
+	 * @param {boolean} [remove] - Set to `true` to unregister the handler function.
+	 * @return {function[]|ComboBox} Returns an array of registered handler functions if arguments are omitted, otherwise returns `this` component instance.
+	 * @see PopupEvent
+	 * @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).
+	 * };
+	 */
+	onPopupEvents(callback, ...args)
+	{
+		return this.event("onPopupEvents", callback, args[0] ?? false);
+	}
+	
+	/**
+	 * Sets or gets the maximum number of items to show in a popup list without having to scroll.
+	 *
+	 * @param {number} size - Defines the maximum amount of items that should be visible in the popup list without having to scroll.
+	 * @return {ComboBox|number} Returns `number` value if argument is omitted, otherwise returns `this` component instance.
+	 */
+	popupSize(...args)
+	{
+		if(args.length > 0) args[0] = parseInt(args[0]); // validate int input value
+		return this.property("popupSize", args);
+	}
+	
+	/**
+	 * 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
+	 * 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
+	 */
+	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]);
+		}
+	}
+	
+	/**
+	 * Finds first item 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}});
+	}
+}