swing-ui 0.1.25 → 1.0.3

package/classes/Window.js

@@ -0,0 +1,609 @@
+import {ShapeContainer} from "./ShapeContainer.js";
+
+/**
+ * Window UI component that extends ShapesContainer class which extends UIComponent.
+ * For more methods for this component check ShapesContainer and UIComponent classes.
+ *
+ * @glass
+ * @global
+ * @example <h2>To create a new custom window class (recommended way for main window):</h2>
+ * class MyWindow extends Window
+ * {
+ *      constructor()
+ *      {
+ *          super("My New Application"); //
+ *      }
+ * }
+ *
+ * // appWindow1 will be accessible globally.
+ * globalThis.appWindow1 = new MyWindow();
+ */
+class Window extends ShapeContainer
+{
+	_shapes = [];
+	temp_token = undefined;
+
+	#owner = null; // used only for modal window
+	#prop = {
+		closeOperation: Window.CloseOperation.Exit,
+		innerOffset: null
+	};
+
+	/**
+	 * Represents the behavior when a close button is clicked or close() method is called.
+	 * Applies to {@link Window} and {@link InternalWindow} components.
+	 *
+	 * @readonly
+	 * @enum {number}
+	 * @property {number} Nothing - Do nothing; the close button has no effect. WindowEvent with type "closing" still gets emitted to report intent to close.
+	 * @property {number} Hide - Hide the window instead of closing it.
+	 * @property {number} Dispose - Release window resources and remove it from display. Emits 2 WindowEvent events, with type "closing" and with "close".
+	 * @property {number} Exit - Terminate the entire application. Emits 2 WindowEvent events, with type "closing" and with "close".
+	 * @see Window
+	 * @see InternalWindow
+	 * @example
+	 * window.closeOperation(Window.CloseOperation.Exit); // setting most common window close operation
+	 */
+	static CloseOperation = Object.freeze({Nothing: 0, Hide: 1, Dispose: 2, Exit: 3});
+
+	/**
+	 * Represents the display state of a {@link Window}. Pass one of these values to {@link Window#state} to get or set the Window's current state.
+	 *
+	 * @readonly
+	 * @enum {number}
+	 * @property {number} Normal - The window is in its default, restored state (not minimized or maximized).
+	 * @property {number} Minimized - The window is collapsed to the taskbar or dock.
+	 * @property {number} Maximized - The window is expanded to fill the entire application area on the screen.
+	 * @property {number} MaximizedHorizontally - The window is maximized horizontally but not vertically. Doesn't apply to {@link InternalWindow} component.
+	 * @property {number} MaximizedVertically - The window is maximized vertically but not horizontally. Doesn't apply to {@link InternalWindow} component.
+	 * @see Window#state
+	 * @see Window#minimize
+	 * @see Window#maximize
+	 * @see InternalWindow#state
+	 * @example <h2>Checking and setting Window state</h2>
+	 * if(window.state() === Window.State.Minimized)
+	 * {
+	 *    window.state(Window.State.Normal);
+	 * }
+	 */
+	static State = Object.freeze({
+		Normal: 0,
+		Minimized: 1,
+		Maximized: 2,
+		MaximizedHorizontally: 3,
+		MaximizedVertically: 4
+	});
+
+	/**
+	 * Represents the type of the window. Used when creating or modifying a window's appearance or behavior.
+	 *
+	 * @readonly
+	 * @enum {number}
+	 * @property {number} Normal - A standard, resizable window with borders, title bar and a taskbar button.
+	 * @property {number} Borderless - A window with a task bar button, but without border and title bar.
+	 * @property {number} Utility - A smaller utility window without a taskbar button, typically used for tools or palettes.
+	 * @property {number} Popup - A popup window, usually without a title bar, borders and taskbar button.
+	 * @see Window#type
+	 * @example
+	 * let window = ne Window("New window", parent_window, Window.Type.Utility);
+	 */
+	static Type = Object.freeze({Normal: 0, Borderless: 1, Utility: 2, Popup: 3});
+
+	/**
+	 * Window component constructor.
+	 *
+	 * @param {string} [text] - Text displayed in Window title bar and in task bar button.
+	 * @param {Window} [owner_window=null] - Enables modal mode. This new Window will always be on top of the owner Window until it is closed.
+	 * @param {Window.Type} [windowType=Window.Type.Normal] - Type of the Window.
+	 * @see Window.Type
+	 * @see Window.CloseOperation
+	 * @example <h2>3 ways to create a new Window:</h2>
+	 * new Window() // without title text D789
+	 * new Window("Window Title Text") // width title text
+	 * new Window("Window Title Text", owner_window, Window.Type.Utility) // for modal window
+	 */
+	constructor(...args)
+	{
+		if(args.length > 1 && args[1] != null && !(args[1] instanceof Window))
+		{
+			throw new Error(`Passed owner of the Windows must be also a Window. Received ${typeof args[1]}`);
+		}
+
+		const arg = {};
+
+		if(args.length > 0 && typeof args[0] === "string") arg.text = args[0];
+		if(arg.text === undefined) delete arg.text;
+
+		if(args[1] != null && args[1] instanceof Window) arg.owner = args[1].id; // set owner Window if provided, making this window modal
+		if(args.length > 2) arg.type = args[2];
+
+		super("Frame", (new.target === Window), ...(Object.keys(arg).length > 0 ? [arg] : []));
+
+		if("owner" in arg) this.#owner = args[1];
+
+		// callback to clear innerOffset cache on UI change
+		const clearOffset = e => {this.#prop.innerOffset = null;};
+		ui.onUIChange(clearOffset); // register callback
+		this.onDispose(e => {ui.onUIChange(clearOffset, true);}); // unregister callback
+
+		//this.finalize(ShapeContainer, Window);
+
+		// load UI definition file
+		if(new.target !== Window && this.applyUIDefinition != null) this.applyUIDefinition(new.target.name); // must be called AFTER super()
+	}
+
+	/**
+	 * Returns Window component that is set as an owner of this Window, or `null` if owner Window was not set.
+	 *
+	 * @readonly
+	 * @type {Window|null}
+	 */
+	get owner()
+	{
+		return this.#owner;
+	}
+
+	/**
+	 * Gets the current Window type.
+	 *
+	 * @readonly
+	 * @type {Window.Type}
+	 * @see Window#Type
+	 */
+	get type()
+	{
+		return this.property("type", []);
+	}
+
+	/**
+	 * Returns the size of the screen that the Window occupies. If the Window is not on any screen, then returns default screen's size. If the Window was never displayed on a screen, then `null` is returned.
+	 *
+	 * @readonly
+	 * @type {Size}
+	 */
+	get screenSize()
+	{
+		return this.property("screenSize");
+	}
+
+	/**
+	 * Returns an offset of each side of content pane of the Window relative to Window's edges. See example below:
+	 *
+	 * @readonly
+	 * @type {Object}
+	 * @example
+	 * // Returned 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;
+	}
+
+	/**
+	 * Sets or gets the operation to perform when a Window close button is clicked by a user or a close() method is called on this Window.
+	 *
+	 * @param {Window.CloseOperation} [operation] - One of Window.CloseOperation enum values. Default is Window.CloseOperation.Close.
+	 * @return {Window|Window.CloseOperation} Returns `this` component if argument is provided, otherwise returns value.
+	 */
+	closeOperation(...args)
+	{
+		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(WindowStateEvent): any} [callback] - The event handler function receiving {@link WindowStateEvent} event object.
+	 * @param {boolean} [remove=false] - Set to `true` to unregister the event handler.
+	 * @returns {this}
+	 * @see Window#State
+	 * @example
+	 * // Example event object:
+	 * const e = {
+	 *   target: Window,            // The component that triggered the event.
+	 *   type: string,              // `change`
+	 *   oldValue: Window.State,    // Previous state
+	 *   newValue: Window.State,    // New state
+	 *   interactive: boolean       // Indicates if the state was changed by user's interaction with window
+	 * };
+	 */
+	onStateChange(...args)
+	{
+		if(args.length === 0) return this.event("onStateChange");
+		return this.event("onStateChange", args[0], args[1] ?? false);
+	}
+
+	/**
+	 * Gets, registers or unregisters an event handler for window events, such as activate, deactivate, closed, etc.
+	 *
+	 * @param {function(WindowEvent): any} [callback] - The event handler function receiving {@link WindowEvent} event object.
+	 * @param {boolean} [remove=false] - Set to `true` to unregister the event handler.
+	 * @returns {this}
+	 *
+	 * @example
+	 * // Example event object:
+	 * const e = {
+	 *   target: Window,            // 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(...args)
+	{
+		if(args.length === 0) return this.event("onWindowEvents");
+		return this.event("onWindowEvents", args[0], args[1] ?? false);
+	}
+
+	/**
+	 * Performs previously specified close operation on this Window.
+	 * To specify what operation should be performed use closeOperation(Window.CloseOperation.[Nothing|Exit|Hide|Dispose])
+	 *
+	 * @return {Window} Returns this window component
+	 */
+	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({control: this.id, set: "close"});
+
+				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({control: this.id, set: "close"});
+				ui.exit(0);
+				break;
+			}
+			case Window.CloseOperation.Nothing:
+			{
+				ui.sendToGUI({control: this.id, set: "close"});
+				break;
+			}
+		}
+
+		return this;
+	}
+
+	/**
+	 * Shows a dialog window asking user to confirm your message. User has an option to press OK or Cancel, which result in returned values `true` or `false` respectively.
+	 *
+	 * @param {string} message - Message to show in dialog window.
+	 * @return {boolean} Returns `boolean` indicating if user confirmed the message or not.
+	 */
+	confirm(message)
+	{
+		return ui.sendToGUI({control: this.id, get: "showConfirmDialog", data: message});
+	}
+
+	/**
+	 * Opens file/directory chooser dialog window. Check example for all possible options.
+	 *
+	 * @param {FileChooserOptions} options - JSON Object with valid options. See example for full list of options.
+	 * @returns {string|string[]|null} Returns `string` path if `multiple` option is `false`, `string[]` if `multiple` option is `true`, or `null` if file chooser was closed without making a selection.
+	 * @example
+	 * window.chooseFile({
+	 *  directory: false,          // `true` for Directory selection, `false` for Files.
+	 *  save: true,               // `true` for `Save` dialog box, `false` for `Open`.
+	 *  multiple: false,           // [true|false] to be able to select multiple files/folders.
+	 *  hidden:false,              // [true|false] to show hidden files.
+	 *  filter:"Documents:doc,docx,txt,rtf|Music:mp3,m4a,ogg,wma|Images:gif,jpg,jpeg,bmp,webp", // File extension can have multiple "." characters, such as "file.d.ts".
+	 *  path:"Initial-Path/file.ext" // Default path to open in the dialog window.
+	 * });
+	 * @see FileChooserOptions
+	 */
+	chooseFile(options)
+	{
+		return ui.sendToGUI({control: this.id, get: "showFileChooser", data: options}, null, true);
+	}
+
+	/**
+	 * Opens color chooser dialog window.
+	 *
+	 * @param {string} [title] - Dialog window title text
+	 * @param {string} [initial_color] - Default color to show in dialog window before a new one is chosen.
+	 * @returns {string|null} Returns a string of a chosen color.
+	 */
+	chooseColor(title = "Choose Color", initial_color = "#000000")
+	{
+		return ui.sendToGUI({
+			control: this.id,
+			get: "showColorPicker",
+			data: {title: title, default: initial_color}
+		}, null, true);
+	}
+
+	/**
+	 * Opens font chooser dialog window.
+	 *
+	 * @param {string} [title] - Dialog window title text
+	 * @param {Object} [initial_font] - Pre-fills dialog window with specified font properties.
+	 * @returns {Object|null} Returns a new chosen font object or `null` if font was not selected.
+	 */
+	chooseFont(title = "Choose Font", initial_font = {})
+	{
+		return ui.sendToGUI({control: this.id, get: "showFontChooser", data: {title: title, font: initial_font}});
+	}
+
+	/**
+	 * Sets or get a window state. Use one of these enum values: Window.State.[Normal|Minimized|Maximized|MaximizedHorizontally|MaximizedVertically]
+	 *
+	 * @param {Window.State} [state] - Setting new window state
+	 * @returns {Window.State|Window} Returns `this` Window if argument is provided, otherwise returns current state.
+	 * @see Window#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);
+	}
+
+	/**
+	 * Convenience method to minimize the Window by setting Window state to Window.State.Minimized.
+	 *
+	 * @return {Window} Returns `this` Window.
+	 * @see Window#State
+	 * @see Window#state
+	 * @see Window#maximize
+	 */
+	minimize()
+	{
+		return this.state(Window.State.Minimized);
+	}
+
+	/**
+	 * Convenience method to maximize the Window by setting Window state to Window.State.Maximized.
+	 *
+	 * @return {Window} Returns `this` Window.
+	 * @see Window#State
+	 * @see Window#state
+	 * @see Window#minimize
+	 */
+	maximize()
+	{
+		return this.state(Window.State.Maximized);
+	}
+
+	/**
+	 * Sets or returns the index or the screen that the Window is on.
+	 *
+	 * @args {number} [index] - Index of the screen where to move this Window. To get a list of screens with indexes use ui.screens().
+	 * @return {Window|number} Returns `this` Window if argument is provided, otherwise returns index of the screen this Window is on.
+	 */
+	screen()
+	{
+		return this.property("screen", arguments);
+	}
+
+	/**
+	 * Sets or gets a default button in this window form. On some systems like Windows OS default button has a different look than other buttons.
+	 *
+	 * @param {Button} button - The button that should be default on this Window. Only last assigned button gets to be default.
+	 * @return {Button|undefined}
+	 */
+	defaultButton(...args)
+	{
+		if(args.length > 0)
+		{
+			if(!(args[0] instanceof Button)) throw new Error("Default button of a Window must be of type Button. " + (typeof args[0]) + " was given.");
+			return this.property("defaultButton", [args[0].id]);
+		}
+		else
+		{
+			const id = this.property("defaultButton", []);
+			const btn = UIComponent.get(id);
+			return btn instanceof Button ? btn : undefined;
+		}
+	}
+
+	/**
+	 * Sets or gets a size of content container of this Window (doesn't include the size of the window borders and a menu bar 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 {Size|Window} Returns `this` Window if called with parameters, otherwise returns the inner size.
+	 * @see Size
+	 */
+	innerSize(...args)
+	{
+		if(args.length > 0)
+		{
+			if(args[0] == null) return this;
+
+			let size = undefined;
+
+			if(typeof args[0] === "object")
+			{
+				if(!("width" in args[0]) || !("height" in args[0])) return this;
+				size = {width: Number.parseInt(args[0].width), height: Number.parseInt(args[0].height)}
+			}
+			else if(args.length > 1)
+			{
+				size = {width: Number.parseInt(args[0]), height: Number.parseInt(args[1])};
+			}
+			else return this;
+
+			if(size.width < 0 || size.height < 0) return this;
+
+			const offset = this.innerOffset;
+			this.#prop.size = {width: size.width + offset.left + offset.right, height: size.height + offset.top + offset.bottom};
+
+			return this.property("innerSize", [size]);
+		}
+
+		return this.property("innerSize", []);
+	}
+
+	/**
+	 * Indicates the minimum size the content container of the Window 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|Window|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 Window#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.x += offset.left + offset.right;
+			s.y += offset.top + offset.bottom;
+
+			return this.minSize(s);
+		}
+		else
+		{
+			let s = this.minSize();
+
+			if(s == null) return null;
+
+			// subtract offset
+			const offset = this.innerOffset;
+			s.x -= (offset.left + offset.right);
+			s.y -= (offset.top + offset.bottom);
+
+			return s;
+		}
+	}
+
+	/**
+	 * Indicates the maximum size the content container of the Window 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|Window|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 Window#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.x += offset.left + offset.right;
+			s.y += offset.top + offset.bottom;
+
+			return this.maxSize(s);
+		}
+		else
+		{
+			let s = this.maxSize();
+
+			if(s == null) return null;
+
+			// subtract offset
+			const offset = this.innerOffset;
+			s.x -= (offset.left + offset.right);
+			s.y -= (offset.top + offset.bottom);
+
+			return s;
+		}
+	}
+
+	/**
+	 * Sets or gets whether window should always stay on top of other windows.
+	 *
+	 * @param {boolean} [value] - Set Window to be on top or not
+	 * @return {Window|boolean} Returns `this` Window if arguments are supplied, otherwise returns `boolean` value.
+	 */
+	alwaysOnTop(...args)
+	{
+		return this.property("alwaysOnTop", args.length > 0 ? [args[0] === true] : []);
+	}
+
+	/**
+	 * Sets or gets the main menu bar for the top of the Window. On macOS, this menu bar appears in the system's top menu bar.
+	 *
+	 * @param {MenuBar} [bar] - The `MenuBar` to set as the primary menu bar.
+	 * @returns {Window|MenuBar|null} Returns the `Window` instance when setting a menu bar; otherwise, returns the currently set `MenuBar`, or `null` if none is set.
+	 */
+	menuBar(...args)
+	{
+		if(args.length === 0) return this.#prop.menuBar ?? null;
+
+		let menuBar = args[0];
+
+		if(menuBar == null) // remove context menu
+		{
+			if(this.#prop.menuBar != null)
+			{
+				this.#prop.menuBar = null;
+				this.#prop.innerOffset = null; // reset offset because it changed
+				return this.property("menuBar", [null]);
+			}
+			return this;
+		}
+		else if(menuBar instanceof globalThis.MenuBar) // add context menu. // can't use !(menu instanceof MenuBar) because MenuBar imports this class, thus would create circular import.
+		{
+			this.#prop.menuBar = menuBar;
+			this.#prop.innerOffset = null; // reset offset because it changed
+			return this.property("menuBar", [menuBar.id]);
+		}
+		else
+		{
+			error(ui._msg[11]);
+			return this;
+		}
+	}
+
+	/**
+	 * Sets of get whether the window may be resized by end user.
+	 *
+	 * @param {boolean} [value] - Enables/disables resizing
+	 * @return {Window|boolean} Returns `this` Window if argument is supplied, otherwise returns `boolean` value.
+	 */
+	resizable(...args)
+	{
+		return this.property("resizable", args);
+	}
+
+	/**
+	 * Sets or gets component opacity float value between 0 and 1 inclusive. Opacity can be set only to Windo with types {@link Window.Type.Borderless} or {@link Window.Type.Popup}.
+	 *
+	 * @param {number} [opacity] - A number between 0 and 1 inclusive.
+	 * @return {number|this} If `opacity` argument is provided, `this` component is returned, otherwise opacity `number` is returned.
+	 */
+	opacity(...args)
+	{
+		return this.property("opacity", args);
+	}
+
+}
+
+export {Window};