swing-ui 0.1.25 → 1.0.3

package/classes/ShapeContainer.js

@@ -0,0 +1,231 @@
+import {Shape} from "./Shape.js";
+import {ComponentContainer} from "./ComponentContainer.js";
+
+/**
+ * ShapeContainer is not a standalone component. ShapeContainer extends UIComponent and serves a purpose to implement Shape related methods and properties. ShapeContainer is extended by {@link Panel} and {@link Window} components.
+ * @class
+ * @global
+ * @see ComponentContainer
+ */
+export class ShapeContainer extends ComponentContainer
+{
+	/**
+	 * ShapeContainer constructor.
+	 * @internal
+	 * @ignore
+	 */
+	constructor(...args)
+	{
+		super(...args);
+	}
+
+	/**
+	 * Returns amount of shapes added to this Window.
+	 *
+	 * @readonly
+	 * @type {number}
+	 */
+	get shapeCount()
+	{
+		return this._shapes.length;
+	}
+
+	/**
+	 * Gets an array of shapes currently added to the component, or sets an array of new shapes while replacing existing ones.
+	 *
+	 * @param {Array<Shape>} [shapes] - An array of Shape objects, such as Rectangle, Line, Ellipse, etc.
+	 * @returns Array<Shape> If called without arguments, an array of shapes is returned, otherwise `this` component instance is returned for chaining.
+	 * @throws {TypeError} When one of passed array elements is not of Shape type.
+	 * @see Shape
+	 */
+	shapes(...args)
+	{
+		if(args.length === 0)
+		{
+			return [...this._shapes];
+		}
+		else if(Array.isArray(args[0]))
+		{
+			// validate new shapes
+			args[0].forEach((shape, i) =>
+			{
+				if(!(args[0][i] instanceof Shape)) throw new TypeError(`Invalid "shape" at index ${i} in the array argument passed to Panel.shapes(shapes).`);
+			});
+
+			const update = this.prop.update !== false;
+			if(update) this.update(false);
+
+			// remove existing shapes
+			for(let i = this._shapes.length - 1; i >= 0; i--) this._shapes[i].remove();
+
+			args[0].forEach(shape => shape.addTo(this));
+
+			if(update) this.update(true);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Gets a Shape at a specified index.
+	 *
+	 * @param {number} i - Index of the shape you want to get
+	 * @returns {Shape} Returns a `Shape` at a specified `index`, or `undefined`, if `index` is out of bounds or invalid.
+	 */
+	shape(i)
+	{
+		return this._shapes[i];
+	}
+
+	/**
+	 * Gets an index of a specified Shape object or sets a new index making the Shape change its layer index position.
+	 *
+	 * @param {Shape} shape - Shape object in question
+	 * @param {number} [new_index] - The new index to assign to the `Shape`. Moves the `Shape` in z-order.
+	 * @return {number} Returns an index of the Shape or -1 if only first argument is passed, or `this` component index if `new_index` is passed.
+	 * @throws {TypeError} When invalid argument type is passed as a `shape` argument.
+	 * @throws {Error} When the shape is not added to this component while attempting to change its index to `new_index`.
+	 */
+	shapeIndex(shape, new_index = undefined)
+	{
+		if(!(shape instanceof Shape)) throw new TypeError(`Invalid argument type. An instance of 'Shape' is expected.`);
+
+		const i = this._shapes.indexOf(shape);
+
+		if(new_index == null) return i;
+
+		if(i === -1) throw new Error(`The Shape is not added to this component.`);
+		else if(new_index >= this._shapes.length) new_index = this._shapes.length - 1;
+		else if(i === new_index) return new_index;
+
+		this._shapes.splice(i, 1);
+		this._shapes.splice(new_index, 0, shape);
+
+		return this.property("shape_index", [{old: i, new: new_index}])
+
+	}
+
+	/**
+	 * Adds a Shape to be drawn on the panel.
+	 *
+	 * @param {Shape} shape - Shape object to draw on this panel
+	 * @param {number} [index] - Set only if you want to insert the Shape at a specific index
+	 * @returns {ShapeContainer} Returns `this` instance of the Panel.
+	 * @see Shape#addTo
+	 */
+	addShape(shape, index = -1)
+	{
+		if(!(shape instanceof Shape)) throw new Error(`Invalid "shape" argument passed to Panel.addShape(shape, ...).`);
+		if(index > this._shapes.length) throw new Error("Index is out of bounds");
+
+		// if already a child at same index, then skip it
+		if(index > -1 && this._shapes[index] === shape) return this;
+
+		if(shape.parent === this) // if parent was already set by shape.addTo() then finish adding
+		{
+			const action = index > -1 ? "insert_shape" : "add_shape";
+			if(index < 0) index = this._shapes.length;
+			this._shapes.splice(index, 0, shape);
+
+			const shapeObject = shape.toObject();
+			shapeObject.index = index;
+
+			ui.sendToGUI({control: this.id, set: action, value: shapeObject});
+		}
+		else // first set new parent to the Shape, then come back to finish
+		{
+			shape.addTo(this, index);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Removes a specified Shape, then the removed Shape is returned.
+	 *
+	 * @param {number|Shape} index_or_shape - Shape or index of the Shape to be removed.
+	 * @return {Shape|boolean} Returns removed Shape, or `false` in case when index is invalid or out of bounds.
+	 * @see Shape#remove
+	 */
+	removeShape(index)
+	{
+		let shape = null;
+
+		// If index is the Shape object to be removed, find its index
+		if(index instanceof Shape)
+		{
+			shape = index;
+			index = this._shapes.indexOf(index);
+			if(index < 0) return false;
+		}
+		else
+		{
+			shape = this._shapes[index];
+			if(shape === undefined) return false;
+		}
+
+		if(shape.parent === this) // remove shape parent first, then come back
+		{
+			shape.remove();
+		}
+		else
+		{
+			// remove the shape
+			this._shapes.splice(index, 1);
+			ui.sendToGUI({control: this.id, set: "remove_shape", value: index});
+		}
+
+		return shape;
+	}
+
+	/**
+	 * @internal
+	 * @ignore
+	 */
+	verifyToken(token)
+	{
+		return (this.temp_token != null && this.temp_token === token);
+	}
+
+	/**
+	 * Registers, unregisters and gets a list of handler functions for Shape events (such as when mouse enters, leaves, mouse button clicks, etc.).
+	 *
+	 * @param {function(ShapeEvent):any} [callback] - Event handler function that receives {@link ShapeEvent} object as an argument. Check example below for event Object format.
+	 * @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 ShapeEvent
+	 * @example
+	 * let handler = function(e){console.log(e);}
+	 * mainForm.panel_1 = new Panel().addTo(mainForm).onPopupEvents(handler);
+	 *
+	 * // event Object format:
+	 * const e = {
+	 *   target: object,        // The Panel component that triggered the event.
+	 *   type: string,          // Possible values: `add`, `remove`, `click`, `mousedown`, `mouseup`, `mouseenter`, `mouseleave`, `mousemove`.
+	 *   x: number,             // X position relative to target.
+	 *   y: number,             // Y position relative to target.
+	 *   shapeIndex: number,    // Index of the shape that triggered the event.
+	 *   dragging: boolean,     // `true` if mouse is down while moving, otherwise false.
+	 *   alt: boolean,          // `true` if Alt key was pressed on keyboard when event was emitted.
+	 *   shift: boolean,        // `true` if Shift key was pressed on keyboard when event was emitted.
+	 *   ctrl: boolean,         // `true` if Control key was pressed on keyboard when event was emitted.
+	 *   modifiers: string,     // Modifiers used when the event was emitted
+	 *   modifiersText: string  // Description of used modifiers
+	 * };
+	 */
+	onShapeEvents(callback, ...args)
+	{
+		let c = callback;
+
+		if(typeof c === "function")
+		{
+			c = e =>
+			{
+				e.shape = this._shapes[e.shapeIndex];
+				callback(e);
+			};
+		}
+
+		return this.event("onShapeEvents", c, args[0] ?? false);
+	}
+}

package/classes/Slider.js

@@ -0,0 +1,172 @@
+
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * Slider UI component is used to set value by sliding a thumb (handle) horizontally or vertically. Slider works only with integer numbers, so decimal places will not work.
+ *
+ * @class
+ * @global
+ */
+export class Slider extends UIComponent
+{
+	/**
+	 * Slider constructor. Creates an instance of Slider UI component.
+	 * @param {string} [text] - Text of the component.
+	 */
+	constructor(...args)
+	{
+		if(args.length > 0) super("Slider", (new.target === Slider), args[0]); else super("Slider", (new.target === Slider));
+		
+		this.finalize(Slider);
+	}
+	
+	/**
+	 * Sets or gets the spacing between minor tick marks (smaller markings) in the Slider.
+	 *
+	 * @param {number} [spacing] - The interval at which minor tick marks are drawn.
+	 * @return {Slider|number} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	minorTickSpacing(...args)
+	{
+		if(args.length > 0) args[0] = parseInt(args[0]);
+		return this.property("minorTickSpacing", args);
+	}
+	
+	/**
+	 * Sets or gets the spacing between major tick marks (larger markings) in the Slider.
+	 *
+	 * @param {number} [spacing] - The interval at which major tick marks are drawn.
+	 * @return {Slider|number} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	majorTickSpacing(...args)
+	{
+		if(args.length > 0) args[0] = parseInt(args[0]);
+		return this.property("majorTickSpacing", args);
+	}
+	
+	/**
+	 * Enables or disables snapping the slider's knob to the nearest tick mark.
+	 *
+	 * @param {boolean} [snap] - If true, the knob will snap to the nearest tick; if false, it moves freely.
+	 * @return {Slider|boolean} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	snapToTicks(...args)
+	{
+		return this.property("snapToTicks", args);
+	}
+	
+	/**
+	 * Shows or hides tick marks on the Slider.
+	 *
+	 * @param {boolean} [visible] - If true, tick marks will be displayed; if false, they will be hidden.
+	 * @return {Slider|boolean} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	showTicks(...args)
+	{
+		return this.property("showTicks", args);
+	}
+	
+	/**
+	 * Shows or hides numeric labels on the Slider.
+	 *
+	 * @param {boolean} [visible] - If true, labels will be displayed; if false, they will be hidden.
+	 * @return {Slider|boolean} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	showLabels(...args)
+	{
+		return this.property("showLabels", args);
+	}
+	
+	/**
+	 * Shows or hides the track (line) behind the slider knob.
+	 *
+	 * @param {boolean} [visible] - If true, the track will be displayed; if false, it will be hidden.
+	 * @return {Slider|boolean} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	showTrack(...args)
+	{
+		return this.property("showTrack", args);
+	}
+	
+	/**
+	 * Sets or gets whether the Slider is inverted (maximum value on the left/top).
+	 *
+	 * @param {boolean} [inverted] - If true, the maximum value is on the left/top; if false, it is on the right/bottom.
+	 * @return {Slider|boolean} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	inverted(...args)
+	{
+		return this.property("inverted", args);
+	}
+	
+	/**
+	 * Sets or gets the minimum value of the Slider.
+	 *
+	 * @param {number} [minValue] - The minimum allowed value.
+	 * @return {Slider|number} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	min(...args)
+	{
+		if(args.length > 0) args[0] = parseInt(args[0]);
+		return this.property("min", args);
+	}
+	
+	/**
+	 * Sets or gets the maximum value of the Slider.
+	 *
+	 * @param {number} [maxValue] - The maximum allowed value.
+	 * @return {Slider|number} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	max(...args)
+	{
+		if(args.length > 0) args[0] = parseInt(args[0]);
+		return this.property("max", args);
+	}
+	
+	/**
+	 * Sets or get integer value of the slider.
+	 *
+	 * @param {number} [value] - Value to display by the slider's handle. Must be between min and max allowed values.
+	 * @return {Slider|number} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	value(...args)
+	{
+		if(args.length > 0) args[0] = parseInt(args[0]);
+		return this.property("value", args);
+	}
+	
+	/**
+	 * Sets or gets the orientation of the Slider.
+	 *
+	 * @param {Orientation} [orientation] - The slider's orientation: `Orientation.Horizontal` or `Orientation.Vertical`.
+	 * @return {Slider|Orientation} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	orientation(...args)
+	{
+		return this.property("orientation", args);
+	}
+	
+	/**
+	 *
+	 * Enables or disables onChange event to be continuously emitted while user is moving the handle and value is changing.
+	 * If disabled, the onChange event will only be invoked after user stopped sliding the knob and releases mouse button.
+	 *
+	 * @param {boolean} [enabled] - If true, change events are emitted during sliding; if false, only when handle is released.
+	 * @return {Slider|boolean} When setting a value, returns this component for chaining; otherwise returns the current value.
+	 */
+	emitWhileSliding(...args)
+	{
+		return this.property("changeWhileSliding", args);
+	}
+	
+	/**
+	 * Indicates if the slider handle is being moved at that moment and not released yet.
+	 *
+	 * @readonly
+	 * @type {boolean}
+	 */
+	get isAdjusting()
+	{
+		return this.property("isAdjusting", []);
+	}
+}

package/classes/Spinner.js

@@ -0,0 +1,172 @@
+
+import {TextComponent} from "./TextComponent.js";
+
+/**
+ * Component that can hold a number, list items, date/time, and IP addresses. Iterate through numbers or list items with up and down buttons or up and down keys (when Spinner has focus).
+ *
+ * @class
+ * @global
+ */
+export class Spinner extends TextComponent
+{
+	/**
+	 * Defines the available spinner data types.
+	 * Determines what type of values the spinner can represent and iterate through.
+	 *
+	 * @readonly
+	 * @enum {number}
+	 * @property {number} Number   Spinner holds and iterates through numeric values.
+	 * @property {number} List     Spinner iterates through values from a predefined list.
+	 * @property {number} DateTime Spinner holds and iterates through date and/or time values.
+	 * @property {number} IPv4     Spinner holds and iterates through IPv4 address values.
+	 * @property {number} IPv6     Spinner holds and iterates through IPv6 address values.
+	 * @see Spinner#constructor
+	 */
+	static Type = Object.freeze({Number: 0, List: 1, DateTime: 2, IPv4: 3, IPv6: 4});
+	
+	/**
+	 * Defines the available step units for {@link Spinner.Type.DateTime} spinners.
+	 * Each unit represents the part of the date or time that changes when incremented or decremented.
+	 *
+	 * @readonly
+	 * @enum {number}
+	 * @property {number} Era               Represents the era (e.g., BC/AD).
+	 * @property {number} Year              Represents the year.
+	 * @property {number} Month             Represents the month.
+	 * @property {number} WeekOfYear        Represents the week of the year.
+	 * @property {number} WeekOfMonth       Represents the week within the month.
+	 * @property {number} DayOfMonth        Represents the day of the month.
+	 * @property {number} DayOfYear         Represents the day of the year.
+	 * @property {number} DayOfWeek         Represents the day of the week.
+	 * @property {number} DayOfWeekInMonth  Represents the nth day of the week within a month.
+	 * @property {number} AM_PM             Represents AM or PM in a 12-hour clock.
+	 * @property {number} Hour              Represents the hour in a 12-hour clock.
+	 * @property {number} HourOfDay         Represents the hour in a 24-hour clock.
+	 * @property {number} Minute            Represents the minute.
+	 * @property {number} Second            Represents the second.
+	 * @property {number} Millisecond       Represents the millisecond.
+	 * @see Spinner#step
+	 */
+	static Step = Object.freeze({Era: 0, Year: 1, Month: 2, WeekOfYear: 3, WeekOfMonth: 4, DayOfMonth: 5, DayOfYear: 6, DayOfWeek: 7, DayOfWeekInMonth: 8, AM_PM: 9, Hour: 10, HourOfDay: 11, Minute: 12, Second: 13, Millisecond: 14});
+	
+	/**
+	 * Creates a new Spinner component for selecting numbers, list items, dates/times, or IP addresses.
+	 *
+	 * @param {Spinner.Type} type - Spinner value type. Valid values are Spinner.Type.[Number (default)|List|DateTime|IPv4|IPv6]
+	 * @param {string|Array<*>} [list_or_format] - Format of how the value should be displayed (for numbers), or Array of list items (when type is Spinner.DataType.List).
+	 * @param {number} [min] - The minimum allowed value (numeric or date)
+	 * @param {number} [max] - The maximum allowed value (numeric or date).
+	 * @param {number|Spinner.Step} [step] - Step increment used when increasing/decreasing values. Pass `number` for Number type of spinner and `Spinner.Step` for DateTime type.
+	 * @example
+	 * // Number Type: new Spinner(type, format, min, max, step_size);
+	 * new Spinner(Spinner.Type.Number, "0.00", 0, 100, 5);
+	 * @example
+	 * // List Type: new Spinner(new Array());
+	 * new Spinner(Spinner.Type.List, ["Monday","Tuesday","Wednesday","Thursday","Friday"]);
+	 * @example
+	 * // DateTime type:
+	 * new Spinner(Spinner.Type.DateTime, new Date(2000, 0, 1), new Date(2030, 11, 31), "yyyy-MM-dd", Spinner.Step.DayOfMonth);
+	 */
+	constructor(type)
+	{
+		let args = {type: parseInt(type)};
+		
+		switch(type)
+		{
+			case Spinner.Type.Number:
+			{
+				args.format = arguments.length > 1 ? String(arguments[1]) : "0.00";
+				args.min = arguments.length > 2 ? arguments[2] : 0;
+				args.max = arguments.length > 3 ? arguments[3] : 100;
+				args.step = arguments.length > 4 ? arguments[4] : 0.05;
+				break;
+			}
+			case Spinner.Type.List:
+			{
+				args.list = arguments[1];
+				break;
+			}
+			case Spinner.Type.DateTime:
+			{
+				args.format = arguments.length > 1 ? String(arguments[1]) : null;
+				args.min = arguments.length > 2 ? arguments[2] : null;
+				args.max = arguments.length > 3 ? arguments[3] : null;
+				args.step = arguments.length > 4 ? parseInt(arguments[4]) : Spinner.Step.Second;
+				break;
+			}
+			case Spinner.Type.IPv4:
+			{
+				break;
+			}
+			case Spinner.Type.IPv6:
+			{
+				break;
+			}
+			default:
+			{
+				args.type = Spinner.Type.Number; //Spinner.Type.Number;
+			}
+		}
+		
+		super("Spinner", (new.target === Spinner), args);
+		
+		this.finalize(Spinner);
+	}
+	
+	/**
+	 * Gets or sets the minimum allowed numeric value for the spinner.
+	 * Applicable only if the spinner was initialized with {Spinner.Type.Number}, {Spinner.Type.DateTime} or {Spinner.Type.IPv4}.
+	 * Returns `null` if spinner type is {Spinner.Type.List}.
+	 *
+	 * @param {number} [value] - The minimum value to set.
+	 * @returns {number | null | Spinner} The current minimum value, `null` if not applicable, or the Spinner instance when setting.
+	 */
+	min()
+	{
+		return this.property("min", arguments);
+	}
+	
+	/**
+	 * Gets or sets the maximum allowed numeric value for the spinner.
+	 * Applicable only if the spinner was initialized with {Spinner.Type.Number}, {Spinner.Type.DateTime} or {Spinner.Type.IPv4}.
+	 * Returns `null` if spinner type is {Spinner.Type.List}.
+	 *
+	 * @param {number} [value] - The maximum value to set.
+	 * @returns {number | null | Spinner} The current maximum value, `null` if not applicable, or the Spinner instance when setting.
+	 */
+	max()
+	{
+		return this.property("max", arguments);
+	}
+	
+	/**
+	 * Gets or sets the step increment/decrement for the spinner when changing values via arrows or keyboard.
+	 * Applicable only if the spinner was initialized with {Spinner.Type.Number}, {Spinner.Type.DateTime}, or {Spinner.Type.IPv4}.
+	 * Returns `null` if spinner type is {Spinner.Type.List}.
+	 *
+	 * @param {number} [value] - The step size to set.
+	 * @returns {number | null | Spinner} The current step size, `null` if not applicable, or the Spinner instance when setting.
+	 */
+	step()
+	{
+		return this.property("step", arguments);
+	}
+
+	/**
+	 * Sets or gets a value displayed in the Spinner component. This method returns number, Date and string types for value depending on the type of the Spinner. To set and get only string value you should use .text() method.
+	 *
+	 * @param {number|string|Date} value - New value to set. For date/time accepted value types are `Date` object or a string in the format `yyyy-MM-dd HH:mm:ss`, `yyyy-MM-dd`, `HH:mm:ss` or Date.toISOString() string.
+	 * @returns {Spinner|number|Date|string} If called without arguments, a current value is returned, otherwise `this` component instance is returned for chaining.
+	 * @see Spinner#text
+	 */
+	value(...args)
+	{
+		if(typeof args[0] === "object" && args[0] instanceof Date) args[0] = {type:"date",value:args[0].getTime()};
+
+		let r = this.property("value", args.length > 0 ? [args[0]] : []);
+
+		if(args.length === 0 && typeof r === "object" && r.type === "date") r = new Date(r.value);
+
+		return r;
+	}
+}

package/classes/SplitView.js

@@ -0,0 +1,82 @@
+
+import {ComponentContainer} from "./ComponentContainer.js";
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * A SplitView is a container component that holds two child components separated by a movable divider. The divider can be dragged to resize the space allocated to each component dynamically.
+ *
+ * Extends {@link ComponentContainer}, which extends {@link UIComponent}.
+ *
+ * NOTE: Set .dividerPosition(value) and add both child components before populating them with child components to make sure descendents' anchor settings yields expected result.
+ *
+ * @class
+ * @global
+ * @see ComponentContainer
+ */
+export class SplitView extends ComponentContainer
+{
+	/**
+	 * Creates an instance of SplitView component.
+	 *
+	 * @param {string} [text} - Optional text property for the component. When adding this component to Tabs this text would be used as a Tab text.
+	 */
+	constructor()
+	{
+		if(arguments.length > 0)
+		{
+			super("SplitView", (new.target === SplitView), arguments[0]);
+		}
+		else
+		{
+			super("SplitView", (new.target === SplitView));
+		}
+		
+		this.finalize(SplitView, ComponentContainer);
+	}
+	
+	/**
+	 * Sets of gets the position of the divider (from top or left depends on orientation).
+	 *
+	 * @param {number} [position] - Position of the divider.
+	 * @return {number|SplitView} If called without parameters, returns current value; otherwise returns this SplitView component for chaining.
+	 * @see SplitView#orientation
+	 */
+	dividerPosition()
+	{
+		return this.property("dividerLocation", arguments);
+	}
+	
+	/**
+	 * Sets of gets the thickness of the divider.
+	 *
+	 * @param {number} [size] - Thickness of the divider in pixels.
+	 * @return {number|SplitView} If called without parameters, returns current value; otherwise returns this SplitView component for chaining.
+	 */
+	dividerSize()
+	{
+		return this.property("dividerSize", arguments);
+	}
+	
+	/**
+	 * Returns an array of current sizes of both child components as an array of objects {width:number, height:number}.
+	 *
+	 * @type {Array<{width:number, height:number}>}
+	 * @readonly
+	 */
+	get panelSizes()
+	{
+		return this.property("panelSizes", arguments);
+	}
+	
+	/**
+	 * Sets or gets an orientation of two sides in relation to each other.
+	 *
+	 * @param {Orientation} [orientation] - One of the value: Orientation.Horizontal, Orientation.Vertical
+	 * @return {number|SplitView} If called without parameters, returns current value; otherwise returns this SplitView component for chaining.
+	 * @see Orientation
+	 */
+	orientation(...args)
+	{
+		return this.property("orientation", args);
+	}
+}