swing-ui 0.1.25 → 1.0.3

package/classes/Separator.js

@@ -0,0 +1,24 @@
+/**
+ * @version 2025-09-23
+ */
+
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * A Separator is used to create a separator line between menu items in a menu or between components in a ToolBar.
+ * Default orientation is horizontal, but a ToolBar will orient the orientation of this Separator making it in Opposite orientation of the ToolBar.
+ *
+ * @class
+ * @global
+ */
+export class Separator extends UIComponent
+{
+	/**
+	 * Separator constructor. Creates an instance of Separator UI component.
+	 */
+	constructor()
+	{
+		super(new.target.name, (new.target === Separator));
+		this.finalize(new.target);
+	}
+}

package/classes/Shape.js

@@ -0,0 +1,584 @@
+/**
+ * Shape object that can be added to Panel to be drawn on component Paint
+ */
+
+import {Stroke} from "./Stroke.js";
+
+/**
+ * Shape class is used to create shapes that can be drawn in the background of {@link Window} or {@link Panel} components. This class is usually extended by other shapes. It can be used by itself only if the ` path ` argument is provided.
+ *
+ * Path of the shape can be generated by adding, subtracting, or intersecting two shapes, then convert the Shape to JSON object using shape.toObject(). Then the resulting object will have a ` path ` property.
+ *
+ * Check out all the shapes that derive from this Shape class: {@link Arc}, {@link Ellipse}, {@link Line}, {@link Polygon}, {@link Polyline}, {@link Rectangle}, and a {@link Text} that can draw text as a shape.
+ *
+ * @class
+ * @global
+ */
+export class Shape
+{
+	#prop = {
+		parent: undefined,
+		x: 0,
+		y: 0,
+		opacity: 1.0,
+		background: undefined,
+		stroke: new Stroke(0),
+		angle: 0,
+		anchor: {x: 0, y: 0},
+		path: undefined,
+		visible: true,
+		active:true,
+		update: true
+	};
+	_type = "path";
+
+	/**
+	 * Shape constructor.
+	 *
+	 * @param {string|undefined} [path] - Path consisting of points. It can be auto-generated by performing operations of one shape to another, such as add() or subtract().
+	 * @param {Stroke|null} [stroke] - A border of the shape.
+	 * @param {string|null} [background] - Color, gradient, image, and background options like in CSS.
+	 * @param {number} [opacity] - Opacity of the shape as a decimal between 0 and 1.
+	 * @param {number} [x] - Position of the shape from left edge.
+	 * @param {number} [y] - Position of the shape from the top.
+	 * @throws {TypeError} When stroke, opacity or other argument types are invalid.
+	 */
+	constructor(path = undefined, stroke = undefined, background = undefined, opacity = 1, x = 0, y = 0)
+	{
+		if(stroke != null && !(stroke instanceof Stroke)) throw new TypeError(`Invalid stroke argument passed. Must be an instance of a Stroke or NULL.`);
+		if(!Number.isFinite(opacity)) throw new TypeError(`Invalid shape opacity argument type. Float from 0 to 1 is expected.`);
+		if(background != null && typeof background !== "string") throw new TypeError(`Invalid shape background argument type. String or NULL is expected.`);
+
+		this.#prop.path = path;
+		this.#prop.stroke = stroke;
+		this.#prop.background = background;
+		this.#prop.opacity = opacity;
+		this.#prop.x = Number.isFinite(x) ? x : 0;
+		this.#prop.y = Number.isFinite(y) ? y : 0;
+	}
+
+	/**
+	 * Add this shape to a container.
+	 *
+	 * @param {ShapeContainer} container - Panel or Window component.
+	 * @param {number} index - Optional index to insert the shape.
+	 * @returns {Shape} Returns `this` Shape instance for chaining.
+	 * @throws {TypeError} When a container is not Panel or Window component.
+	 * @throws {Error} When specified index is out of bounds.
+	 * @see ShapeComponent#addShape
+	 * @see Shape#remove
+	 */
+	addTo(container, index = -1)
+	{
+		// validate new parent
+		if(!(container instanceof Panel || container instanceof Window)) throw new TypeError(`Invalid argument. Shape container must be a Panel or Window component.`);
+		if(index > container._shapes.length) throw new Error("Index is out of bounds");
+
+		// if already a child at same index, then skip it
+		if(index > -1 && this.#prop.parent === container && container.shape(index) === this) return this;
+
+		this.remove();
+
+		this.#prop.parent = container;
+
+		container.addShape(this, index);
+
+		return this;
+	}
+
+	/**
+	 * Removes this Shape from its container component.
+	 *
+	 * @returns {Shape} `this` Shape container for chaining.
+	 * @see ShapeComponent#removeComponent
+	 * @see Shape#addTo
+	 */
+	remove()
+	{
+		if(this.#prop.parent !== undefined)
+		{
+			const p = this.#prop.parent;
+			this.#prop.parent = undefined;
+			p.removeShape(this);
+		}
+		return this;
+	}
+
+	/**
+	 * Returns current parent component (Window or Panel), or `undefined` if the shape isn't added to any component.
+	 *
+	 * @readonly
+	 * @type {Window|Panel|undefined}
+	 */
+	get parent()
+	{
+		return this.#prop.parent;
+	}
+
+	/**
+	 * Sets or gets a {@link Stroke} of the shape.
+	 *
+	 * @param {Stroke} [stroke] - Stroke object
+	 * @return {Stroke|this} When called without parameters, current `Stroke` is returned; otherwise this `Shape` is returned for method chaining.
+	 */
+	stroke(...args)
+	{
+		if(args.length > 0)
+		{
+			if(!(args[0] instanceof Stroke)) throw new Error(`Invalid stroke argument. It must be of Stroke type.`); // validate stroke input
+
+			this.#prop.stroke = args[0];
+			this.update("stroke");
+			return this;
+		}
+		else
+		{
+			return this.#prop.stroke;
+		}
+	}
+
+	/**
+	 * Returns a JSON object that contains shape properties.
+	 *
+	 * @param {string} [include="all"] - Specified what to include. "all" is default. Valid values are: "all", "stroke", "background", "points", "basic". Each shape that derives from this `Shape` class may also have it's own values.
+	 * @return {Shape} Returns this `Shape` for method chaining.
+	 */
+	toObject(include = "all")
+	{
+		let shape = {};
+
+		if(include === "all") shape.type = this.#prop.path !== undefined ? "path" : this._type;
+		if(["all", "location"].includes(include))
+		{
+			shape.x = this.#prop.x;
+			shape.y = this.#prop.y;
+		}
+		if(["all", "opacity"].includes(include)) shape.opacity = this.#prop.opacity;
+		if(["all", "stroke"].includes(include) && this.#prop.stroke instanceof Stroke) shape.stroke = this.#prop.stroke.toObject();
+		if(["all", "rotation"].includes(include))
+		{
+			shape.angle = this.#prop.angle;
+			shape.anchor = this.#prop.anchor;
+		}
+		if(["all", "path"].includes(include) && this.#prop.path !== undefined) shape.path = this.#prop.path;
+		if(["all", "background"].includes(include)) shape.background = this.#prop.background;
+		if(["all", "visible"].includes(include)) shape.visible = this.#prop.visible;
+		if(["all", "active"].includes(include)) shape.active = this.#prop.active;
+
+		return shape;
+	}
+
+	/**
+	 * Converts JSON object back to Shape. To convert Shape to object use Shape.toObject() function.
+	 *
+	 * @param {object} object - An object that has properties to recreate a Shape object.
+	 * @returns {Shape} Returns a new instance of `Shape`.
+	 */
+	static fromObject(object)
+	{
+		const shape = new Shape(object.path ?? undefined, Stroke.fromObject(object.stroke) ?? new Stroke(0), object.background ?? undefined, object.opacity ?? 1, object.x ?? 0, object.y ?? 0);
+
+		shape._type = object.type ?? "path";
+		shape.#prop.angle = object.angle ?? 0;
+		shape.#prop.anchor = object.anchor ?? 0;
+
+		if(object._points !== undefined) object._points = object.points;
+		if(object.size !== undefined) shape._size = object.size;
+		if(object.hole_size !== undefined) shape._hole_size = object.hole_size;
+		if(object.start_angle !== undefined) shape._start_angle = object.start_angle;
+		if(object.extent !== undefined) shape._extent = object.extent;
+		if(object.arc_type !== undefined) shape._arc_type = object.arc_type;
+		if(object.arc_size !== undefined) shape._arc_size = object.arc_size;
+		if(object.text !== undefined) shape._text = object.text;
+		if(object.font !== undefined) shape._font = object.font;
+
+		return shape;
+	}
+
+	/**
+	 * Updates properties of this Shape. It's called by other methods of Shape object when shape properties change.
+	 *
+	 * @param {string|boolean} [what="all"] - What to update: "all", "min", "stroke", "background", "points". Shapes that derive from this class may also have their own values. Pass a `boolean` to enable and disable this shape redraw. Before making multiple changes to the Shape it helps to disable redraw, make the changes, then enable redraw.
+	 * @returns {void}
+	 * @internal
+	 * @ignore
+	 */
+	update(what = "all")
+	{
+		if(typeof what === "boolean")
+		{
+			if(what === this.#prop.update) return;
+			else
+			{
+				this.#prop.update = what;
+				if(what) what = "all";
+				else return;
+			}
+		}
+
+		if(this.#prop.parent === undefined) return;
+
+		let i = this.#prop.parent.shapeIndex(this);
+
+		if(i < 0) throw new Error(`This Shape "${this._type}" doesn't belongs to this component "${this.#prop.parent.constructor.name}".`);
+
+		let obj = this.toObject(what);
+		obj.index = i;
+
+		ui.sendToGUI({control: this.#prop.parent.id, set: "update_shape", value: obj});
+	}
+
+	/**
+	 * Sets or gets location of the shape relative to top-left corner of its parent component.
+	 *
+	 * @param {number|Point} [x] - X position integer or a Point position object (e.g., {x:10,y:40}).
+	 * @param {number} [y] - Y position integer.
+	 * @return {Point|this} If called without arguments, current position object is returned; otherwise this shape is returned for method chaining.
+	 * @see Point
+	 */
+	position(...args)
+	{
+		if(args.length > 0)
+		{
+			if(typeof args[0] === "object")
+			{
+				if(typeof args[0].x === "number" && Number.isFinite(args[0].x)) this.#prop.x = args[0].x;
+				if(typeof args[0].y === "number" && Number.isFinite(args[0].y)) this.#prop.y = args[0].y;
+			}
+			else
+			{
+				if(typeof args[0] === "number" && Number.isFinite(args[0])) this.#prop.x = args[0];
+				if(typeof args[1] === "number" && Number.isFinite(args[1])) this.#prop.y = args[1];
+			}
+
+			this.update("location");
+			return this;
+		}
+		else
+		{
+			return {x: this.#prop.x, y: this.#prop.y};
+		}
+	}
+
+	/**
+	 * Moves the Shape by adding the specified x and y values to its current position.
+	 * The function shifts the element's position relative to current position.
+	 * If arguments are invalid integer values, the Shape will not be moved.
+	 *
+	 * @param {number} [dx=0] - Delta x (can be positive or negative number)
+	 * @param {number} [dy=0] - Delta y (can be positive or negative number)
+	 * @return {Shape} Returns `this` Shape instance.
+	 */
+	move(dx, dy)
+	{
+		if(!Number.isFinite(dx) || !Number.isFinite(dy)) return this;
+		return this.position(this.#prop.x + dx, this.#prop.y + dy);
+	}
+
+	/**
+	 * Sets or gets X position of the shape relative to left edge of its parent component.
+	 *
+	 * @param {number} [x] - X position integer.
+	 * @return {number|this} If called without arguments, current X position is returned; otherwise this shape is returned for method chaining.
+	 * @see Shape#position
+	 */
+	x()
+	{
+		if(arguments.length > 0)
+		{
+			if(typeof arguments[0] === "number" && Number.isFinite(arguments[0]))
+			{
+				this.#prop.x = arguments[0];
+				this.update("location");
+			}
+			return this;
+		}
+		else
+		{
+			return this.#prop.x;
+		}
+	}
+
+	/**
+	 * Sets or gets Y position of the shape relative to top edge of its parent component (for Window parent component gets Y position from the top of content area).
+	 *
+	 * @param {number} [y] - Y position integer.
+	 * @return {number|this} If called without arguments, current Y position is returned; otherwise this shape is returned for method chaining.
+	 * @see Shape#position
+	 */
+	y()
+	{
+		if(arguments.length > 0)
+		{
+			if(typeof arguments[0] === "number" && Number.isFinite(arguments[0]))
+			{
+				this.#prop.y = arguments[0];
+				this.update("location");
+			}
+			return this;
+		}
+		else
+		{
+			return this.#prop.y;
+		}
+	}
+
+	/**
+	 * Gets or sets the opacity (transparency) of the shape.
+	 *
+	 * @param {number} [opacity] - Decimal value between 0 and 1 (inclusive).
+	 * @returns {number|this} If called without arguments, returns the current opacity; otherwise, returns this shape for method chaining.
+	 */
+	opacity()
+	{
+		if(arguments.length > 0)
+		{
+			this.#prop.opacity = parseFloat(arguments[0]);
+			this.update("opacity");
+			return this;
+		}
+
+		return this.#prop.opacity;
+	}
+
+	/**
+	 * Gets or sets the rotation angle of the shape around its anchor.
+	 *
+	 * Use the `anchor()` method to specify the anchor position relative to the shape.
+	 *
+	 * The default anchor is set to the top-left corner of the shape's bounding rectangle (even for non-rectangular shapes).
+	 *
+	 * @param {number} [angle] - Rotation angle in degrees. Values below 0 or above 360 are normalized to the range 0–360 using the modulus operator (%).
+	 * @return {number|this} If called without arguments, returns the current value; otherwise this shape is returned for method chaining.
+	 * @see Shape#anchor
+	 */
+	angle(angle = undefined)
+	{
+		if(angle === undefined) return this.#prop.angle;
+
+		if(typeof angle !== "number") return this;
+
+		if(angle !== this.#prop.angle)
+		{
+			if(angle !== 0)
+			{
+				angle = angle % 360;
+				if(angle < 0) angle += 360; // for performance do this with IF
+			}
+
+			this.#prop.angle = angle;
+
+			this.update("rotation");
+		}
+		return this;
+	}
+
+	/**
+	 * Sets or gets the anchor position relative to the shape, around which the shape can be rotated using the `angle()` method.
+	 *
+	 * The default anchor is at the top-left corner of the shape's bounding rectangle (even for non-rectangular shapes).
+	 *
+	 * @param {Point} [anchor] - Anchor point around which the shape rotates when the rotation angle is not 0.
+	 * @returns {Point|this} If called without arguments, returns the current anchor; otherwise, returns this shape for method chaining.
+	 * @see Point
+	 * @see Shape#angle
+	 */
+	anchor()
+	{
+		if(arguments.length > 0)
+		{
+			let anchor = (arguments.length === 2) ? {x: arguments[0], y: arguments[1]} : arguments[0];
+
+			if(typeof anchor.x === "number") this.#prop.anchor.x = anchor.x;
+			if(typeof anchor.y === "number") this.#prop.anchor.y = anchor.y;
+			this.update("rotation");
+			return this;
+		}
+		else
+		{
+			return this.#prop.anchor;
+		}
+	}
+
+	/**
+	 * Sets or gets the background of the shape.
+	 *
+	 * The `background` value can be a string that contains a mixture of background color, image path (relative or absolute), base64 encoded image string, linear-gradient, radial-gradient, like in CSS in web browsers. Some features may not be supported though.
+	 * Background settings like position, image stretching or repeating, opacity and more are supported.
+	 *
+	 * See examples below.
+	 *
+	 * @param {string} [background] - Background string. If omitted, returns the current value.
+	 * @returns {this|string} If called without parameters, returns this shape instance; otherwise returns current background.
+	 *
+	 * @example
+	 * shape.background("#FF000055 url(images/bg.png) center no-repeat opacity=0.6 10px 15px linear-gradient(#DDDDDD55, #F8F8F855 10%) / auto);
+	 * panel.background("url(data:image/png;base64,As8fE4fdt1r.....)")); // supports base64 encoded image string
+	 */
+	background()
+	{
+		if(arguments.length > 0)
+		{
+			this.#prop.background = arguments[0];
+			this.update("background");
+			return this;
+		}
+
+		return this.#prop.background;
+	}
+
+	/**
+	 * Returns the size of a shape. Does not set a new size. Some shapes override this function and size can be set for those shapes. (e.g. Rectangle, Ellipse)
+	 *
+	 * @param {Size} [size] - Size formatted object, but only for shapes that allow setting new size, such as Rectangle or Ellipse.
+	 * @returns {Size|this} If called without parameters, returns current size, or `null` if the shape is not added to a component. When setting size, this shape instance is returned for method chaining.
+	 * @throws Error When the shape is not added to a container.
+	 * @see Size
+	 */
+	size(...args)
+	{
+		if(args.length > 0) throw new Error(`${this.constructor.name} doesn't allow setting size(...). For ${this.constructor.name} you can only use size() to get current size of this shape.`);
+		if(this.#prop.parent === undefined) throw new Error(`Can't get shape size before the shape is added to a container.`);
+
+		if(args.length === 0)
+		{
+			const index = this.#prop.parent.shapeIndex(this);
+			return ui.sendToGUI({control: this.#prop.parent.id, get: "shapeSize", data: index});
+		}
+		else
+		{
+			return this;
+		}
+	}
+
+	/**
+	 * Sets or gets whether the shape is visible.
+	 *
+	 * @param {boolean} [visible] - `true` to show, `false` to hide.
+	 * @return {boolean|Shape} When setting a value, this shape is returned; otherwise current value is returned.
+	 */
+	visible(...args)
+	{
+		if(args.length === 0) return this.#prop.visible;
+
+		args[0] = args[0] === true;
+
+		if(args[0] !== this.#prop.visible)
+		{
+			this.#prop.visible = args[0];
+			this.update("visible");
+		}
+
+		return this;
+	}
+
+	/**
+	 * Sets or gets whether this shape is active (`true` by default).
+	 *
+	 * An inactive shape (`active(false)`) does not produce events `mousedown`, `mouseup`, `click`, `mouseenter`, `mouseleave`, `mousemove` on {@link Panel#onShapeEvents}, and is skipped during mouse hit-testing. This means the mouse "passes through" the shape as if it weren't there — if another shape lies beneath it, that shape is considered to be under the mouse instead.
+	 *
+	 * Settings active to `false` may be useful for purely decorative shapes (e.g. background fills, watermarks, static overlays) that shouldn't intercept or respond to mouse interaction.
+	 *
+	 * @param {boolean} [active] - `false` to make the shape inactive (ignored by shape events and mouse hit-testing), `true` to restore normal behavior. Omit to get the current value.
+	 * @return {boolean|Shape} When called without arguments, returns the current value; otherwise returns this `Shape` instance for method chaining.
+	 * @default true
+	 * @see Panel#onShapeEvents
+	 * @see ShapeEvent
+	 */
+	active(...args)
+	{
+		if(args.length === 0) return this.#prop.active;
+
+		args[0] = args[0] === true;
+
+		if(args[0] !== this.#prop.active)
+		{
+			this.#prop.active = args[0];
+			this.update("active");
+		}
+
+		return this;
+	}
+
+	/**
+	 * Adds another shape to this shape. Stroke of this shape is kept (stroke of another shape is disregarded).
+	 *
+	 * @param {Shape} shape - Another shape object that would be added to this shape.
+	 * @returns {this} Returns this shape for method chaining.
+	 */
+	add(shape)
+	{
+		if(!(shape instanceof Shape)) return false;
+		this.#prop.path = ui.sendToGUI({
+			java: "shapeOperation",
+			operation: "Add",
+			shape: this.toObject(),
+			otherShape: shape.toObject()
+		}, r => {return r.value;});
+		this._type = "path";
+		this.update("all");
+		return this;
+	}
+
+	/**
+	 * Removes an area of a specified shape from this shape. Stroke of this shape is kept (stroke of another shape is disregarded).
+	 *
+	 * @param {Shape} shape - Another shape object that would be subtracted from this shape.
+	 * @returns {this} Returns this shape for method chaining.
+	 */
+	subtract(shape)
+	{
+		if(!(shape instanceof Shape)) return false;
+		this.#prop.path = ui.sendToGUI({
+			java: "shapeOperation",
+			operation: "Subtract",
+			shape: this.toObject(),
+			otherShape: shape.toObject()
+		}, r => {return r.value;});
+		this._type = "path";
+		this.update("all");
+		return this;
+	}
+
+	/**
+	 * Remove an area from this shape where this shape and provided shape don't intersect, leaving only area where these shapes do intersect. Stroke of this shape is kept (stroke of another shape is disregarded).
+	 *
+	 * @param {Shape} shape - Another shape object.
+	 * @returns {this} Returns this shape for method chaining.
+	 */
+	intersect(shape)
+	{
+		if(!(shape instanceof Shape)) return false;
+		this.#prop.path = ui.sendToGUI({
+			java: "shapeOperation",
+			operation: "Intersect",
+			shape: this.toObject(),
+			otherShape: shape.toObject()
+		}, r => {return r.value;});
+		this._type = "path";
+		this.update("all");
+		return this;
+	}
+
+	/**
+	 * Checks if this shape intersects (touches) with another shape. Both of these shapes must be added to the same component for this to work.
+	 *
+	 * @param {Shape} shape - Intercepting shape
+	 * @return {boolean|null} Returns boolean on successful check or `null` if the check failed to be performed.
+	 */
+	intersects(shape)
+	{
+		if(this.#prop.parent === undefined || this.#prop.parent !== shape.parent) return false;
+
+		const i1 = this.#prop.parent.shapeIndex(this);
+		const i2 = this.#prop.parent.shapeIndex(shape);
+
+		if(i1 === -1 || i2 === -1) return false;
+
+		return ui.sendToGUI({
+			control: this.#prop.parent.id,
+			get: "shapeIntersects",
+			data: {i1: i1, i2: i2}
+		}, r => {return r.value;});
+	}
+}