swing-ui 0.1.25 → 1.0.1

package/classes/InternalWindow.js

@@ -0,0 +1,397 @@
+
+import {ComponentContainer} from "./ComponentContainer.js";
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * InternalWindow UI component. Extends ComponentContainer, which extends UIComponent class.
+ * Internal window is a Window like component, but it can only be added to InternalWindowContainer for window-in-window experience.
+ * By default, InternalWindow is not visible. Use .visible(true) or .show() to make it visible.
+ *
+ * For more methods for this component check UIComponent class.
+ * @class
+ * @global
+ */
+export class InternalWindow extends ComponentContainer
+{
+	#prop = {
+		closeOperation: Window.CloseOperation.Dispose,
+		innerOffset: null
+	};
+
+	/**
+	 * InternalWindow constructor.
+	 *
+	 * @param {string} [text] - Window title text
+	 */
+	constructor()
+	{
+		if(arguments.length > 0)
+		{
+			super("InternalFrame", (new.target === InternalWindow), arguments[0]);
+		}
+		else
+		{
+			super("InternalFrame", (new.target === InternalWindow));
+		}
+		
+		this.prop.innerOffset = null;
+		
+		this.finalize(InternalWindow, ComponentContainer);
+
+		// callback to clear innerOffset cache
+		const clearOffset = e=>{this.prop.innerOffset = null;};
+		ui.onUIChange(clearOffset); // register callback
+		this.onDispose(e=>{ui.onUIChange(clearOffset, true);}); // unregister callback
+	}
+	
+	/**
+	 * Sets or gets the operation to perform when the InternalWindow's close button is clicked by a user or a close() method is called on this InternalWindow.
+	 *
+	 * Default value is `Window.CloseOperation.Dispose`.
+	 *
+	 * @param {Window.CloseOperation} [operation] - One of Window.CloseOperation enum values. (default is `Dispose`)
+	 * @return {InternalWindow|Window.CloseOperation} Returns `this` component if argument is provided, otherwise returns value.
+	 */
+	closeOperation(...args) // nothing, hide, dispose
+	{
+		if(args.length === 0) return this.#prop.closeOperation;
+
+		this.#prop.closeOperation = args[0];
+		return this.property("closeOperation", args);
+	}
+	
+	/**
+	 * Gets, registers or unregisters an event handler for when the state of the Window changes between normal, minimized, maximized.
+	 *
+	 * @param {function(Object): any} [callback] - The event handler function. Receives an event object.
+	 * @param {boolean} [remove=false] - Set to `true` to unregister the event handler.
+	 * @returns {this}
+	 *
+	 * @example
+	 * // Example event object:
+	 * const e = {
+	 *   target: InternalWindow,    // The component that triggered the event.
+	 *   type: string,              // `change`
+	 *   fromState: Window.State,   // Previous state
+	 *   toState: Window.State,     // New state
+	 *   interactive: boolean       // Indicates if the state was changed by user's interaction with window
+	 * };
+	 */
+	onStateChange(callback, ...args)
+	{
+		return this.event("onStateChange", callback, args[0] ?? false);
+	}
+	
+	/**
+	 * Gets, registers or unregisters an event handler for window events, such as activate, deactivate, close, etc.
+	 *
+	 * @param {function(Object): any} [callback] - The event handler function. Receives an event object.
+	 * @param {boolean} [remove=false] - Set to `true` to unregister the event handler.
+	 * @returns {this}
+	 *
+	 * @example
+	 * // Example event object:
+	 * const e = {
+	 *   target: InternalWindow,    // The component that triggered the event.
+	 *   type: string,              // `activate`, `deactivate`, `minimize`, `restore`, `closing`, `close`, `show`
+	 *   interactive: boolean       // Indicates if triggered by user's interaction with window
+	 * };
+	 */
+	onWindowEvents(callback, ...args)
+	{
+		return this.event("onWindowEvents", callback, args[0] ?? false);
+	}
+	
+	/**
+	 * Performs previously specified close operation on this InternalWindow.
+	 * To specify what operation should be performed use closeOperation(Window.CloseOperation.[Nothing|Exit|Hide|Dispose])
+	 *
+	 * @return {InternalWindow} Returns this window component
+	 */
+	close()
+	{
+		const msg = {control: this.id, set: "close"};
+
+		switch(this.#prop.closeOperation)
+		{
+			case Window.CloseOperation.Dispose:
+			{
+				this.emit("onWindowEvents", {type: "closing", interactive: false});
+				this.emit("onWindowEvents", {type: "close", interactive: false});
+
+				ui.sendToGUI(msg);
+
+				this.destroy();
+				break;
+			}
+			case Window.CloseOperation.Hide:
+			{
+				this.hide();
+				break;
+			}
+			case Window.CloseOperation.Exit:
+			{
+				this.emit("onWindowEvents", {type: "closing", interactive: false});
+				this.emit("onWindowEvents", {type: "close", interactive: false});
+				this.emit("onDispose", {type: "dispose"});
+				ui.sendToGUI(msg);
+				ui.exit(0);
+				break;
+			}
+			case Window.CloseOperation.Nothing:
+			{
+				ui.sendToGUI(msg);
+				break;
+			}
+		}
+
+		return this;
+	}
+	
+	/**
+	 * Sets or get a window state. Use one of these enum values: Window.State.[Normal|Minimized|Maximized]
+	 *
+	 * @param {Window.State} [state] - Setting new window state
+	 * @returns {Window.State|Window} Returns `this` Window if argument is provided, otherwise returns current state.
+	 * @example
+	 * window.state(Window.State.Maximized);
+	 * if(window.state() === Window.State.Maximized) console.log("It works!");
+	 */
+	state()
+	{
+		if(arguments.length > 0) arguments[0] = parseInt(arguments[0]);
+		return this.property("state", arguments);
+	}
+	
+	/**
+	 * Sets or gets whether minimize button in window title bar should be visible.
+	 * @param {boolean} [value] - `true` to show (default), `false` - to hide.
+	 * @return {InternalWindow|boolean} Returns `this` component instance if argument is set, otherwise returns current value.
+	 */
+	minimizable()
+	{
+		return this.property("canMinimize", arguments);
+	}
+	
+	/**
+	 * Sets or gets whether maximize button in window title bar should be visible.
+	 * @param {boolean} [value] - `true` to show (default), `false` - to hide.
+	 * @return {InternalWindow|boolean} Returns `this` component instance if argument is set, otherwise returns current value.
+	 */
+	maximizable()
+	{
+		return this.property("canMaximize", arguments);
+	}
+	
+	/**
+	 * Sets or gets whether close button in window title bar should be visible.
+	 * @param {boolean} [value] - `true` to show (default), `false` - to hide.
+	 * @return {InternalWindow|boolean} Returns `this` component instance if argument is set, otherwise returns current value.
+	 */
+	closable()
+	{
+		return this.property("canClose", arguments);
+	}
+	
+	/**
+	 * Sets or gets the ability to resize the window in GUI. Programmatically it can still be resized even when this is disabled.
+	 * @param {boolean} [value] - `true` to enable (default), `false` - to disable.
+	 * @return {InternalWindow|boolean} Returns `this` component instance if argument is set, otherwise returns current value.
+	 */
+	resizable()
+	{
+		return this.property("canResize", arguments);
+	}
+	
+	/**
+	 * Sets or gets the ability to move the window in GUI by dragging title bar or resizing. Programmatically it can still be moved and resized even when this is disabled.
+	 * This may not be supported in Linux and some other systems.
+	 *
+	 * @param {boolean} [value] - `true` to enable (default), `false` - to disable.
+	 * @return {InternalWindow|boolean} Returns `this` component instance if argument is set, otherwise returns current value.
+	 */
+	movable()
+	{
+		return this.property("canMove", arguments);
+	}
+	
+	/**
+	 * Sets or gets whether the InternalWindow should be above other internal windows in default layer. It puts the InternalWindow component in a higher layer. More than one InternalWindow can be in the top layer.
+	 *
+	 * @param {boolean} [value] - `true` to set enable, `false` to disable (default).
+	 * @return {InternalWindow|boolean} Returns `this` component instance if argument is set, otherwise returns current value.
+	 */
+	alwaysOnTop()
+	{
+		return this.property("alwaysOnTop", arguments);
+	}
+	
+	/**
+	 * Make this window be selected (activated) or not.
+	 *
+	 * @param {boolean} [selected] - `true` to activate, `false` to deactivate.
+	 * @return {InternalWindow|boolean} Returns `this` component instance if argument is set, otherwise returns current value.
+	 */
+	selected()
+	{
+		if(this.parent == null) throw Error(`Cannot call selected() on InternalWindow before this InternalWindow is added to InternalWindowContainer.`);
+
+		if(arguments.length === 0)
+		{
+			return (this.parent.selectedWindow() === this);
+		}
+		else
+		{
+			if(arguments[0] === true)
+			{
+				this.parent.selectedWindow(this);
+			}
+			else
+			{
+				this.parent.selectedWindow(null);
+			}
+			
+			return this;
+		}
+	}
+	
+	/**
+	 * Sets or gets a size of content container of this Window (doesn't include the size of the window borders like size() function does).
+	 *
+	 * @param {number|Size} [width_or_size] - Width integer or a Size object as a sole parameter.
+	 * @param {number} [height] - Integer height value (required if the first argument is a numeric width).
+	 * @return {InternalWindow|Size} Returns `this` InternalWindow component if called with parameters, otherwise returns the inner size.
+	 * @see Size
+	 */
+	innerSize(...args)
+	{
+		if(args.length > 0)
+		{
+			const size = {width: 0, height: 0};
+			
+			if(args.length === 1)
+			{
+				if(typeof args[0] === "object" && "width" in args[0] && "height" in args[0])
+				{
+					size.width = parseInt(args[0].width);
+					size.height = parseInt(args[0].height);
+				}
+				else
+				{
+					return this; // invalid input
+				}
+			}
+			else if(args.length > 1)
+			{
+				size.width = parseInt(args[0]);
+				size.height = parseInt(args[1]);
+			}
+			
+			size.width += this.innerOffset.left + this.innerOffset.right;
+			size.height += this.innerOffset.top + this.innerOffset.bottom;
+			
+			return this.size(size);
+		}
+		else
+		{
+			return {
+				width: this.size().width - (this.innerOffset.left + this.innerOffset.right),
+				height: this.size().height - (this.innerOffset.top + this.innerOffset.bottom)
+			};
+		}
+	}
+	
+	/**
+	 * Indicates the minimum size the content container of the InternalWindow it can be resized to. It overrides previously set minSize() value.
+	 *
+	 * @param {number|Size} width_or_size - Width, or a Size formatted object as a sole parameter.
+	 * @param {number} height - Height of the component.
+	 * @returns {Size|InternalWindow|null} If called without parameters, current minimum inner Size is returned or `null` if it wasn't previously set; otherwise returns `this` component instance for chaining.
+	 * @see InternalWindow#maxInnerSize
+	 * @see UIComponent#minSize
+	 * @see Size
+	 */
+	minInnerSize(...args)
+	{
+		if(args.length > 0)
+		{
+			let s = (typeof args[0] === "object") ? {...args[0]} : {width: args[0], height: args[1]};
+			
+			// add offset
+			const offset = this.innerOffset;
+			s.width += offset.left + offset.right;
+			s.height += offset.top + offset.bottom;
+			
+			this.minSize(s);
+		}
+		else
+		{
+			let s = this.minSize();
+			
+			if(s == null) return null;
+			
+			// subtract offset
+			const offset = this.innerOffset;
+			s.width -= (offset.left + offset.right);
+			s.height -= (offset.top + offset.bottom);
+			
+			return s;
+		}
+	}
+	
+	/**
+	 * Indicates the maximum size the content container of the InternalWindow it can be resized to. It overrides previously set maxSize() value.
+	 *
+	 * @param {number|Size} width_or_size - Width, or a Size formatted object as a sole parameter.
+	 * @param {number} height - Height of the component.
+	 * @returns {Size|InternalWindow|null} If called without parameters, current maximum inner Size is returned or `null` if it wasn't previously set; otherwise returns `this` component instance for chaining.
+	 * @see InternalWindow#minInnerSize
+	 * @see UIComponent#maxSize
+	 * @see Size
+	 */
+	maxInnerSize(...args)
+	{
+		if(args.length > 0)
+		{
+			let s = (typeof args[0] === "object") ? {...args[0]} : {width: args[0], height: args[1]};
+			
+			// add offset
+			const offset = this.innerOffset;
+			s.width += offset.left + offset.right;
+			s.height += offset.top + offset.bottom;
+			
+			this.maxSize(s);
+		}
+		else
+		{
+			let s = this.maxSize();
+			
+			if(s == null) return null;
+			
+			// subtract offset
+			const offset = this.innerOffset;
+			s.width -= (offset.left + offset.right);
+			s.height -= (offset.top + offset.bottom);
+			
+			return s;
+		}
+	}
+	
+	/**
+	 * Gets the offset (in pixels) from each edge of the window to the content container.
+	 * @type {Object}
+	 * @example
+	 * // Returned offset object format:
+	 * {
+	 *     top: number,
+	 *     right: number,
+	 *     bottom: number,
+	 *     left: number
+	 * }
+	 */
+	get innerOffset()
+	{
+		if(this.prop.innerOffset == null) this.prop.innerOffset = this.property("innerOffset", []);
+		return this.prop.innerOffset;
+	}
+}

package/classes/InternalWindowContainer.js

@@ -0,0 +1,93 @@
+
+import {UIComponent} from "./UIComponent.js";
+import {ComponentContainer} from "./ComponentContainer.js";
+import {InternalWindow} from "./InternalWindow.js";
+import {ScrollableComponent} from "./ScrollableComponent.js";
+
+/**
+ * InternalWindowContainer UI component, extends ScrollableComponent class.
+ * Internal window container is a component designed to contain InternalWindow components.
+ *
+ * For more methods for this component check {@link ComponentContainer}, {@link ScrollableComponent} and {@link UIComponent} classes.
+ * @class
+ * @global
+ */
+class InternalWindowContainer extends ComponentContainer
+{
+	/**
+	 * InternalWindowContainer constructor.
+	 * @example
+	 * const container = new InternalWindowContainer().size(600, 500).addTo(window);
+	 * const win1 = new InternalWindow("New Window Title").addTo(container);
+	 */
+	constructor()
+	{
+		if(arguments.length > 0)
+		{
+			super("DesktopPane", (new.target === InternalWindowContainer), arguments[0]);
+		}
+		else
+		{
+			super("DesktopPane", (new.target === InternalWindowContainer));
+		}
+
+		this.finalize(InternalWindowContainer, ComponentContainer);
+	}
+
+	/**
+	 * Sets or gets currently selected InternalWindow component.
+	 *
+	 * @window [InternalWindow] [window] - InternalWindow component that should become selected.
+	 * @return {InternalWindowContainer|InternalWindow|null} - If setting, returns `this` component instance. If getting, returns selected InternalWindow or `null` (if there are no windows added yet).
+	 */
+	selectedWindow(...args)
+	{
+		if(args.length > 0)
+		{
+			if(!(args[0] instanceof InternalWindow)) return this;
+
+			args[0] = args[0].id;
+
+			return this.property("selected", args);
+		}
+
+		let id = this.property("selected", args);
+
+		return id > -1 ? UIComponent.get(id) : null;
+	}
+
+	/**
+	 * Sets or gets an index of a selected InternalWindow component.
+	 *
+	 * @param {number} [index] - Index of an item to select.
+	 * @returns {number|InternalWindowContainer} If index is specified, then `this` component instance is returned, otherwise currently selected InternalWindow index is returned.
+	 * @see InternalWindow
+	 * @see InternalWindowContainer#selectedWindow
+	 */
+	selectedIndex(...args)
+	{
+		if(args.length > 0)
+		{
+			if(!Number.isSafeInteger(args[0])) return this;
+			return this.selectedWindow(this.child(args[0]))
+		}
+
+		return this.childIndex(this.selectedWindow());
+	}
+	
+	/**
+	 * Prevents internal windows from being moved outside of visible area of window container. Otherwise windows can be move beyond the boundaries and scroll bars would appear to scroll to those windows.
+	 * This may not work on some systems yet.
+	 *
+	 * @param {boolean} [enforce] - To enable border enforcement set `true`, to disable set `false.
+	 * @return {InternalWindowContainer|boolean} If setting, returns `this` component instance, otherwise returns `boolean` value.
+	 */
+	enforceBoundaries()
+	{
+		return this.property("enforceBoundaries", arguments);
+	}
+}
+
+ComponentContainer.implementClass(InternalWindowContainer, ScrollableComponent);
+
+export {InternalWindowContainer};

package/classes/Label.js

@@ -0,0 +1,52 @@
+
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * Label UI component, extends UIComponent class.
+ * Label can be used to display plain text, HTML content, and image as an icon.
+ *
+ * For more methods for this component check UIComponent class.
+ * @class
+ * @global
+ */
+export class Label extends UIComponent
+{
+	/**
+	 * Label constructor.
+	 * @param {string} [text] - Initial text to display in the label.
+	 * @example <h2>Few ways to create and use Label:</h2>
+	 * // Setting text in constructor
+	 * const label1 = new Label("New label text");
+	 *
+	 * // Setting text after instantiation
+	 * const label2 = new Label().text("Second label text");
+	 *
+	 * // setting an image icon
+	 * const label2 = new Label().icon("images/icon.png");
+	 *
+	 * // setting HTML content to be rendered in the label component
+	 * const label2 = new Label("<html><body><h1>Label Header</h1><p>New paragraph</p></body></html>");
+	 */
+	constructor()
+	{
+		if(arguments.length > 0)
+		{
+			super("Label", (new.target === Label), arguments[0]);
+		}
+		else
+		{
+			super("Label", (new.target === Label));
+		}
+		
+		this.finalize(Label);
+	}
+	
+	/**
+	 * Returns current size of an icon, or `undefined` when no icon has been set or icon failed to load.
+	 * @type {Object|undefined}
+	 */
+	get iconSize()
+	{
+		return this.property("iconSize", []);
+	}
+}

package/classes/Line.js

@@ -0,0 +1,105 @@
+
+import {Shape} from "./Shape.js";
+
+/**
+ * A `Line` shape that extends the {@link Shape} class.
+ *
+ * Line is a geometric line that doesn't have an area to be filled. For the line to be visible you specify the stroke size to be more that 0.
+ *
+ * Line points are relative to the position of the `Line` shape. If you daw multiple lines that are related to each other, make sure to set same position for each of the lines.
+ * @class
+ * @global
+ * @see Shape
+ */
+export class Line extends Shape
+{
+	_points = new Array(4);
+	
+	/**
+	 * Creates an instance of a Line shape.
+	 *
+	 * @param {Stroke} stroke - A border of the shape.
+	 * @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} [point1] - An object with X and Y coordinates {x: number, y: number}.
+	 * @param {number} [point2] - An object with X and Y coordinates {x: number, y: number}.
+	 */
+	constructor(stroke, opacity = 1, x = 0, y = 0, point1 = {x: 0, y: 0}, point2 = {x: 100, y: 100})
+	{
+		super(undefined, stroke, null, opacity, x, y);
+		this._type = "line";
+
+		this._points = [point1.x, point1.y, point2.x, point2.y];
+	}
+	
+	/**
+	 * Sets or gets the first point of the line.
+	 *
+	 * @param {number|{x:number, y:number}} x - X  coordinate of the point, or an object with X and Y coordinates {x: number, y: number}.
+	 * @param {number} [y] - Y coordinate of the point (required only if `x` parameter is a number).
+	 * @returns {Line|Point} If called without parameters, returns current point; otherwise returns this Line shape for chaining.
+	 */
+	point1()
+	{
+		if(arguments.length > 0)
+		{
+			if(typeof arguments[0] === "object")
+			{
+				arguments[1] = arguments[0].y;
+				arguments[0] = arguments[0].x;
+			}
+
+			this._points[0] = arguments[0];
+			this._points[1] = arguments[1];
+			this.update("points");
+			return this;
+		}
+		
+		return {x: this._points[0], y: this._points[1]};
+	}
+	
+	/**
+	 * Sets or gets the second point of the line.
+	 *
+	 * @param {number|{x:number, y:number}} x - X  coordinate of the point, or an object with X and Y coordinates {x: number, y: number}.
+	 * @param {number} [y] - Y coordinate of the point (required only if `x` parameter is a number).
+	 * @return {Line|Point} If called without parameters, returns current point; otherwise returns this Line shape for chaining.
+	 */
+	point2()
+	{
+		if(arguments.length > 0)
+		{
+			if(typeof arguments[0] === "object")
+			{
+				arguments[1] = arguments[0].y;
+				arguments[0] = arguments[0].x;
+			}
+
+			this._points[2] = arguments[0];
+			this._points[3] = arguments[1];
+			this.update("points");
+			return this;
+		}
+
+		return {x: this._points[2], y: this._points[3]};
+	}
+	
+	/**
+	 * 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 shape = super.toObject(include);
+		
+		if(this._type === "line")
+		{
+			if(include === "all" || include === "points") shape.points = this._points;
+		}
+		
+		return shape;
+	}
+}