swing-ui 0.1.25 → 1.0.1

package/classes/ComponentContainer.js

@@ -0,0 +1,828 @@
+import path from "node:path";
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * ComponentContainer is not a standalone component and should not be instantiated.
+ * It provides methods and members for managing child components.
+ * ComponentContainer is extended by {@link Window}, {@link InternalWindowContainer}, {@link InternalWindow}, {@link Panel}, {@link ToolBar}, {@link MenuBar}, {@link Menu}, {@link ContextMenu}, {@link Tabs}, {@link SplitView} and a {@link ScrollPane}.
+ * @class
+ * @global
+ */
+export class ComponentContainer extends UIComponent
+{
+	#_children = []; // child components of this component
+	#descriptorObject = null;
+
+	static preInitProperties = ["position", "size", "innerSize"];
+	static postInitProperties = ["defaultButton", "state", "visible"]; // state must be applied after all children apply anchor property
+
+	/**
+	 * ComponentContainer constructor.
+	 * @internal
+	 * @ignore
+	 */
+	constructor(...args)
+	{
+		// try to load UI from .ui.json file before calling super to override Window type if present.
+		const classObject = new.target;
+		let root = null;
+
+		// Do it only if our UI class was extended by a custom class (branch, not a leaf)
+		if(!args[1] && (args[0] === "Panel" || args[0] === "Frame" || args[0] === "InternalFrame"))
+		{
+			LOAD_FILE:{
+				// find path of the UI class
+				const regex = new RegExp(`at new ${classObject.name} \\((.+?):\\d+:\\d+\\)`);
+				const match = new Error().stack.match(regex);
+				let ui_file = match ? match[1] : null;
+
+				// if path can't be found in the stack, skip it
+				if(ui_file == null) break LOAD_FILE;
+
+				// skip UI components that are in classes directory
+				//if(/node_modules[\\/]+swing-ui[\\/]+classes[\\/]/.test(ui_file)) break LOAD_FILE;
+
+				ui_file = ui_file.split("?", 2)[0]; // removes everything after "?"
+
+				if(ui_file.startsWith("file:///")) ui_file = ui_file.replace(ui.os === "windows" ? "file:///" : "file://", "");
+
+				// convert class file path to UI file path with .ui.json
+				ui_file = ui_file.replaceAll("%20", " ").replace(/\.[^/.]+$/, "") + ".ui.json"; // replaces %20 with spaces, removes file extension, adds new extension
+
+				if(ui.os === "windows" && ui_file.startsWith("/")) ui_file = ui_file.substring(1);
+
+				// check if the UI file exists
+				if(!ui.fileExists(ui_file)) break LOAD_FILE;
+
+				const ui_dir = path.dirname(ui_file);
+
+				let data = null;
+
+				// read .ui.json file
+				try
+				{
+					data = ui.readFile(ui_file);
+				}catch(ex)
+				{
+					throw new Error(`Failed to read UI definition file: ${ui_file}\n\n${ex.message}\n`);
+				}
+
+				try
+				{
+					root = JSON.parse(data);
+				}catch(ex)
+				{
+					throw new Error(`Failed to parse UI definition JSON file: ${ui_file}\n\n${ex.message}\n`);
+				}
+
+				root.version = Number.parseFloat(root.version ?? "0");
+				root.File = ui_file;
+				root.Dir = ui_dir;
+
+				// grab Window type from definition file and override the Window type passed as an argument
+				if(root.version > 0)
+				{
+					if(root.component?.type === "Window" && root.component?.windowType !== undefined)
+					{
+						if(args[2] == null) args[2] = {};
+
+						args[2].type = root.component.windowType;
+						delete root.component.windowType; // we don't need it anymore
+
+						args[2].text = root.component.text;
+						delete root.component.text; // we don't need it anymore
+					}
+				}
+				else
+				{
+					if(root.class === "Window" && root.properties?.type !== undefined)
+					{
+						if(args[2] == null) args[2] = {};
+						args[2].type = root.properties.type;
+						delete root.properties.type; // we don't need it anymore
+					}
+				}
+			}
+		}
+
+		super(...args);
+
+		this.#descriptorObject = root;
+
+		if(this.#descriptorObject == null)
+		{
+			this.applyComponentProperties = null;
+			this.applyUIDefinition = null;
+		}
+	}
+
+	/**
+	 * Gets an array of child components.
+	 *
+	 * A new array of child components is created each time `.children` is accessed, so you may not want to use it directly inside a `for(let i=0; i < component.children.length, i++){}` or `while(...){}` loops. First save it to a variable, then use it in such loop.
+	 *
+	 * In loops `for..in`, `for..of` or `component.children.forEach((c, i)=>{...})` it's accessed only once, so you are looping through the same array.
+	 *
+	 * @readonly
+	 * @type {Object[]}
+	 * @example <h2>Looping through Window's components</h2>
+	 * // method 1
+	 * for(child of window.children)
+	 * {
+	 *     ...
+	 * }
+	 *
+	 * // method 2
+	 * const _children = window.children;
+	 * for(let i = 0; i < _children.length; i++)
+	 * {
+	 *     const child = _children[i];
+	 *     ...
+	 * }
+	 *
+	 * // method 3
+	 * window.children.each(child=>{
+	 *     ...
+	 * });
+	 */
+	get children()
+	{
+		return [...this.#_children];
+	}
+
+	/**
+	 * Gets the number of components added to this container.
+	 * @readonly
+	 * @type {number}
+	 */
+	get childCount()
+	{
+		return this.#_children.length;
+	}
+
+	//region Setters / Getters
+
+	/**
+	 * Returns a child component at specified index, or `null` if index is outside of range.
+	 *
+	 * @param {number} index - Component index (z order).
+	 * @return {UIComponent|null} A child component at specified index, or `null` if there is no child at specified index.
+	 */
+	child(index)
+	{
+		return this.#_children[index] ?? null;
+	}
+
+	/**
+	 * Gets or sets the index of a child component within this container. Setting new index changes z-order of the component.
+	 *
+	 * @param {Object} child - Child component
+	 * @param {number} [new_index] - The new index to assign to the child. Moves the component in z-order.
+	 * @return {this|null|number} If `new_index` is provided, returns `this` component. If the child is not found in this container, returns `null`. Otherwise, returns the child's current z-index.
+	 */
+	childIndex(child, new_index = undefined)
+	{
+		const i = this.#_children.indexOf(child);
+
+		if(new_index == null)
+		{
+			return i;
+		}
+		else if(i > -1 && Number.isSafeInteger(new_index))
+		{
+			new_index = parseInt(new_index);
+			child.verifyComponent();
+			const args = [Math.min(Math.max(0, parseInt(new_index)), this.#_children.length)]; // validate index
+
+			if(i !== args[0])
+			{
+				this.#_children.splice(i, 1);
+				this.#_children.splice(args[0], 0, child);
+
+				child.property("z", args); // update in GUI
+			}
+		}
+		return this;
+	}
+
+	/**
+	 * Adds a child component to this container component.
+	 *
+	 * @param {object} component - UI Component that can be a child of this component.
+	 * @param {number|object} [data_or_index] - Argument to pass some extra data (such as Tab Name to add Panel to Tabs), or index at which to insert the child. By default component is added to the end.
+	 * @returns {this} Returns an instance of `this` component for chaining.
+	 * @see UIComponent#addTo
+	 * @example <h2>Adding a component at specified index 5</h2>
+	 * panel.addChild(new CheckBox("Enabled checkbox").position(10, 15), 5); // adds to panel and positions at (10,15) coordinates
+	 *
+	 * @example <h2>Adding a component at specified index</h2>
+	 * tabs.addChild(new Panel(), {text: "Registration", enabled: true, tooltip: "Create new account", icon: "images/user.png"});
+	 */
+	addChild(component, ...args)
+	{
+		// verify component validity
+		if(typeof component !== "object" || !(component instanceof UIComponent)) throw Error(`'component' must be derived from UIComponent of swing-ui module.`);
+
+		this.verifyComponent();
+		component.verifyComponent();
+
+		if(!this.isContainer) throw new Error(`Cannot add ${component.constructor.name} to ${this.constructor.name}. ${this.constructor.name} cannot contain components.`);
+		if(component === this) throw new Error(`Cannot add ${component.constructor.name} to itself.`);
+		if(this.insideOf(component)) throw new Error(`Cannot add component's ancestor to the component.`);
+
+		// remove from previous parent
+		if(component.parent_id !== null) component.remove();
+
+		// add to this container component
+		component.parent_id = this.id;
+
+		let msg = {control: component.id, get: "parent", data: {parent: this.id, index: -1}};
+
+		if(args.length > 0)
+		{
+			if(typeof args[0] === "number")
+			{
+				msg.data.index = parseInt(args[0]);
+			}
+			else if(typeof args[0] === "object")
+			{
+				Object.assign(msg.data, args[0]); // add data for components like Tabs
+				if(msg.data.index != null) msg.data.index = parseInt(msg.data.index);
+			}
+		}
+
+		if(msg.data.index < 0)
+		{
+			delete msg.data.index;
+			this.#_children.push(component);
+		}
+		else
+		{
+			if(msg.data.index > this.#_children.length) msg.data.index = this.#_children.length;
+			this.#_children.splice(msg.data.index, 0, component); // add at specified index
+		}
+
+		const result = ui.sendToGUI(msg);
+
+		// check if adding was allowed by GUI
+		if(result !== true) throw new Error(`${component.constructor.name} can't be added to ${this.constructor.name}`);
+
+		// reset position & size for Tabs' and ScrollPane's new components
+		if(this instanceof Tabs || this instanceof ScrollPane || this instanceof ToolBar)
+		{
+			component.position(null);
+			component.size(null);
+		}
+		else
+		{
+			// apply right and bottom locations set earlier
+			if("right" in component.prop.location) component.right(component.prop.location.right);
+			if("bottom" in component.prop.location) component.bottom(component.prop.location.bottom);
+			if("right" in component.prop.size || "bottom" in component.prop.size)
+			{
+				const containerSize = (this instanceof Window || this instanceof InternalWindow) ? this.innerSize() : this.size();
+
+				if("right" in component.prop.size)
+				{
+					const w = containerSize.width - component.x() - component.prop.size.right;
+					delete component.prop.size.right;
+
+					if("bottom" in component.prop.size)
+					{
+						let h = containerSize.height - component.y() - component.prop.size.bottom;
+						delete component.prop.size.bottom;
+
+						component.size(w, h);
+					}
+					else
+					{
+						component.width(w);
+					}
+				}
+			}
+		}
+		// emit event
+		setImmediate(() =>
+		{
+			if(!(this.destroyed ?? false))
+				this.emit("onContainerEvents", {type: "add", child: component});
+		});
+
+		return this;
+	}
+
+	/**
+	 * Removes component's child by child object or child index.
+	 *
+	 * @param {object|number} child_or_index - Child component object or index of the child.
+	 * @param {boolean} [recursive=false] - Boolean indicates if all descendents of this child should also be removed.
+	 * @returns {UIComponent|null} The removed child component, or `null` if there is no child at specified index.
+	 */
+	removeChild(child_or_index, recursive = false)
+	{
+		let child = undefined;
+		let i = -1;
+
+		if(typeof child_or_index === "object")
+		{
+			if(!child_or_index instanceof UIComponent) throw new Error(`Invalid argument passed to removeChild(). Component object or index integer is expected.`);
+			i = this.#_children.indexOf(child_or_index);
+			if(i > -1) child = child_or_index; // check if it's a child
+		}
+		else if(typeof child_or_index === "number")
+		{
+			i = child_or_index;
+			child = this.#_children[i];
+		}
+
+		if(child == null || i === -1) return null;
+
+		// remove recursively, in reverse order
+		if(recursive) for(let c = child.childCount - 1; c >= 0; c--) child.removeChild(c, true);
+
+		// disassociate from parent
+		child.parent_id = null;
+
+		// remove from children array
+		this.#_children.splice(i, 1);
+
+		// remove this element from its parent in GUI
+		ui.sendToGUI({control: child.id, set: "remove"});
+
+		// emit event (! MUST BE NOW, because a bit later it may be destroyed)
+		this.emit("onContainerEvents", {type: "remove", child: child});
+
+		return child;
+	}
+
+	/**
+	 * Removes the control from its parent control and from a list of all components. Also prepares this component to be garbage-collected in JavaScript and GUI to free RAM.
+	 *
+	 * @param {boolean} [recursive=false] - Set to true to also destroy all of its descendants recursively
+	 * @returns {void}
+	 */
+	destroy(...args)
+	{
+		if(this.destroyed) return;
+
+		const recursive = (args.length > 0 && args[0] === true);
+
+		// remove all child components, from last to first (IMPORTANT)
+		for(let i = this.#_children.length - 1; i >= 0; i--)
+		{
+			try
+			{
+				if(recursive)
+				{
+					this.#_children[i].destroy(true);
+				}
+				else
+				{
+					this.removeChild(i);
+				}
+			}catch(ex)
+			{error(ex);}
+		}
+
+		super.destroy(...args);
+	}
+
+	/**
+	 * Checks if passed component is a descendant of this container component.
+	 *
+	 * @param descendant - Child component to check.
+	 * @returns {boolean} If the descendant component is inside of this component.
+	 * @throws {TypeError} When passed argument is not an instance of UIComponent.
+	 * @see UIComponent#insideOf
+	 */
+	contains(descendant)
+	{
+		if(!(descendant instanceof UIComponent)) throw new TypeError(`Argument type is invalid. Only UI component is expected.`)
+		let parent = descendant.parent;
+
+		while(parent)
+		{
+			if(parent === this) return true;
+			parent = parent.parent;
+		}
+
+		return false;
+	}
+	//endregion
+
+	//region Events
+
+	/**
+	 * Gets, registers or unregisters an event handler function for container-related events
+	 * triggered when a child component is added or removed.
+	 *
+	 * @param {function(ContainerEvent): any} [callback=undefined] - The event handler function that receives a {@link ContainerEvent} object. Pass `null` to unregister all handler functions.
+	 * @param {boolean} [remove=false] - Set to `true` to unregister the event handler.
+	 * @returns {this|function[]} An array of handler functions if no arguments are passed, otherwise `this` component for method chaining.
+	 * @see ContainerEvent
+	 * @example
+	 * // Example event object:
+	 * const e = {
+	 *   target: object,  // The container component that triggered the event.
+	 *   type: string,    // `add`, `remove`.
+	 *   child: object    // The child component that was added or removed
+	 * };
+	 */
+	onContainerEvents(...args)
+	{
+		if(args.length === 0) return this.event("onContainerEvents");
+		if(!this.isContainer) throw new Error(`Calling onContainerEvents() on a non-container component is not allowed.`);
+		return this.event("onContainerEvents", args[0], args[1] ?? false);
+	}
+
+	//endregion
+
+	//region UI designer file Processing
+
+	/**
+	 * Loads UI Components and properties from UI designer file FILE_NAME.ui.json where FILE_NAME is the name of JavaScript file of the component.
+	 *
+	 * @param {string} class_name - Class name for which to load UI
+	 * @private
+	 * @ignore
+	 */
+	applyUIDefinition(class_name)
+	{
+		// Apply UI to this component
+		if(this.#descriptorObject != null)
+		{
+			const common = {
+				ui_file: this.#descriptorObject.File,
+				ui_dir: this.#descriptorObject.Dir,
+				radio_grouping: [],
+				anchors: {},
+				isRelativePath: p => (typeof p === "string" && p.length > 0 && !p.startsWith("data:") && !p.startsWith("http:") && !p.startsWith("https:") && !p.startsWith("ftp:") && !path.isAbsolute(p)),
+				validateComponent: c =>
+				{
+					if(!("type" in c)) throw new TypeError(`Component is missing "type" and will not be loaded.`);
+					if(typeof globalThis[c.type] !== "function") throw new TypeError(`Component has invalid type '${c.type}' and will not be loaded.`);
+					if(!("ref" in c)) throw new TypeError(`Component '${c.type}' is missing "ref" reference property and will not be loaded.`);
+					if(c.ref in this) throw new Error(`Component '${c.type}' has 'ref' reference '${c.ref}' matches another component's reference or other property and will not be loaded. Duplicate name detected.`);
+				}
+			};
+
+			// Parse UI Designer file
+			this.update(false);
+			if(this.#descriptorObject.version === 1.0)
+			{
+				try
+				{
+					common.validateComponent(this.#descriptorObject.component);
+				}catch(ex)
+				{
+					error(`${ex.name}: ${ex.message}`, false);
+				}
+
+				this.applyComponentPropertiesV1_0(this, this.#descriptorObject.component, common);
+			}
+			else
+			{
+				error(`UI descriptor file version is not supported:\n\n${this.#descriptorObject.File}`, false);
+			}
+			this.#descriptorObject = null;
+			this.update(true);
+
+			// apply grouping to radio components
+			for(const _el of common.radio_grouping)
+			{
+				_el[1] = this[_el[1]];
+				// verify that components are from same class
+				if(_el[1] instanceof _el[0].constructor) _el[0].group(_el[1]);
+			}
+
+			// apply anchors after all components are added and sized
+			Object.entries(common.anchors).forEach(([ref, value]) => {
+				this[ref].anchor(value);
+			});
+		}
+
+		// delete these functions to make sure they can't be called again
+		this.applyComponentProperties = null;
+		this.applyComponentPropertiesV1_0 = null;
+		this.applyUIDefinition = null;
+	}
+
+	/**
+	 * @private
+	 */
+	applyComponentPropertiesV1_0(component, properties, common)
+	{
+		const ref = properties.ref;
+		delete properties.ref;
+
+		const class_name = properties.type;
+		delete properties.type;
+
+		const children = properties.children ?? [];
+		delete properties.children;
+
+		const events = properties.events ?? [];
+		delete properties.events;
+
+		// append directory to icon path if icon path isn't absolute
+		if(common.isRelativePath(properties.icon)) properties.icon = path.join(common.ui_dir, properties.icon);
+
+		// make icon paths absolute
+		if(component instanceof List || component instanceof ComboBox || component instanceof Tree)
+		{
+			if("items" in properties && Array.isArray(properties.items))
+			{
+				// recursive-substitute method to change icon paths to absolute
+				let _stack = [...properties.items];
+				while(_stack.length > 0)
+				{
+					const item = _stack.pop();
+					if(!(typeof item === "object") || item === null) continue;
+					if(common.isRelativePath(item.icon)) item.icon = path.join(common.ui_dir, item.icon);
+					if("children" in item && Array.isArray(item.children)) _stack.push(...item.children);
+				}
+			}
+
+			if(component instanceof Tree && "icons" in properties) // tree custom icons
+			{
+				if(properties.icons != null)
+				{
+					for(const key of Object.keys(properties.icons))
+					{
+						if(common.isRelativePath(properties.icons[key])) properties.icons[key] = path.join(common.ui_dir, properties.icons[key]);
+					}
+				}
+			}
+		}
+		else if(component instanceof Table)
+		{
+			if("columns" in properties && Array.isArray(properties.columns))
+			{
+				const _c = properties.columns;
+
+				// make sure icons' paths are absolute
+				for(let c = 0; c < _c.length; c++)
+				{
+					if(common.isRelativePath(_c[c].icon)) _c[c].icon = path.join(common.ui_dir, _c[c].icon);
+
+					// if column type is "icon", make rows' icons' paths absolute in this column
+					if(_c[c].type === "icon" && "rows" in properties && Array.isArray(properties.rows))
+					{
+						for(let r = 0; r < properties.rows.length; r++)
+						{
+							let _r = properties.rows[c] ?? [];
+
+							if(common.isRelativePath(_r[c])) _r[c] = path.join(common.ui_dir, _r[c]);
+						}
+					}
+				}
+			}
+		}
+
+		// apply properties: call function of each property and pass its value
+
+		// check if pre-initialization properties are present
+		const preInitProps = (component instanceof Window && ComponentContainer.preInitProperties.some(key => key in properties));
+		const postInitProps = (component instanceof Window && ComponentContainer.postInitProperties.some(key => key in properties));
+
+		// apply pre-init props first
+		if(preInitProps)
+		{
+			for(const prop of ComponentContainer.preInitProperties)
+			{
+				if(!(prop in properties)) continue;
+
+				if(typeof component[prop] === "function")
+				{
+					component[prop](properties[prop]);
+				}
+				else
+				{
+					console.error(`${class_name}.${prop} is not a valid property for one of your components in your .ui.json file:\n\n${common.ui_file}`);
+				}
+
+				delete properties[prop]; // no longer needed
+			}
+		}
+
+		// load context menus
+		if("contextMenus" in properties)
+		{
+			if(Array.isArray(properties.contextMenus))
+			{
+				properties.contextMenus.forEach(json_child =>
+				{
+					try
+					{
+						common.validateComponent(json_child);
+					}catch(ex)
+					{
+						error(`Failed to load a context menu. ${ex.name}: ${ex.message}`, false);
+						return;
+					}
+
+					this[json_child.ref] = new globalThis[json_child.type]();
+					this.applyComponentPropertiesV1_0(this[json_child.ref], json_child, common);
+				});
+			}
+
+			delete properties.contextMenus;
+		}
+
+		if(component instanceof Window)
+		{
+			// load main menu bar
+			if("menuBar" in properties)
+			{
+				try
+				{
+					common.validateComponent(properties.menuBar);
+				}catch(ex)
+				{
+					error(`Failed to load a menu bar. ${ex.name}: ${ex.message}`, false);
+				}
+
+				const bar = new globalThis[properties.menuBar.type]();
+				this.applyComponentPropertiesV1_0(bar, properties.menuBar, common);
+				component.menuBar(bar);
+				delete properties.menuBar;
+			}
+
+			// load tray icons
+			if("trayIcons" in properties)
+			{
+				if(Array.isArray(properties.trayIcons))
+				{
+					properties.trayIcons.forEach(json_child =>
+					{
+						try
+						{
+							common.validateComponent(json_child);
+						}catch(ex)
+						{
+							error(`Failed to load a tray icon. ${ex.name}: ${ex.message}`, false);
+							return;
+						}
+
+						const trayIcon = new globalThis[json_child.type]();
+						component.onDispose(e => {if(!trayIcon.destroyed) trayIcon.destroy();}); // destroy the tray icon when window gets disposed
+						this[json_child.ref] = trayIcon;
+						this.applyComponentPropertiesV1_0(trayIcon, json_child, common);
+					});
+				}
+
+				delete properties.trayIcons;
+			}
+		}
+
+		// apply properties
+		for(const prop of Object.keys(properties))
+		{
+			if(postInitProps && ComponentContainer.postInitProperties.includes(prop)) continue; // skip post-init props
+
+			if(prop === "group")
+			{
+				common.radio_grouping.push([component, properties[prop]]);
+				continue;
+			}
+
+			if(typeof component[prop] !== "function")
+			{
+				error(`"${prop}" is not valid property for ${class_name} component in .ui.json file:\n\n${common.ui_file}`, false);
+				continue;
+			}
+
+			let value = properties[prop];
+
+			switch(prop)
+			{
+				case "contextMenu":
+				{
+					if(this[value] instanceof ContextMenu)
+					{
+						component[prop](this[value]); // replace name of context menu with actual object
+					}
+					else
+					{
+						error(`ContextMenu reference "${value}" in ${class_name} "${ref ?? "this"}" is broken in file: \n\n${common.ui_file}`, false);
+					}
+					break;
+				}
+				case "items":
+				{
+					if(component instanceof Tree)
+					{
+						component[prop]([0], value);
+					}
+					else
+					{
+						component[prop](value);
+					}
+					break;
+				}
+				case "anchor":
+				{
+					common.anchors[ref] = value;
+					break;
+				}
+				default:
+				{
+					component[prop](value);
+				}
+			}
+		}
+
+		// add components
+		if(Array.isArray(children))
+		{
+			children.forEach(json_child =>
+			{
+				try
+				{
+					common.validateComponent(json_child);
+				}catch(ex)
+				{
+					error(`${ex.name}: ${ex.message}`, false);
+					return;
+				}
+
+				const child_ref = json_child.ref;
+				this[child_ref] = new globalThis[json_child.type]();
+				this.applyComponentPropertiesV1_0(this[child_ref], json_child, common);
+				component.addChild(this[child_ref]);
+			});
+		}
+
+		// apply post-init props
+		if(postInitProps)
+		{
+			for(const prop of ComponentContainer.postInitProperties)
+			{
+				if(!(prop in properties)) continue;
+
+				if(typeof component[prop] !== "function")
+				{
+					error(`"${prop}" is not valid property for ${class_name} in your ui.json file:\n\n${common.ui_file}`, false);
+					continue;
+				}
+
+				switch(prop)
+				{
+					case "defaultButton":
+					{
+						if(component[properties[prop]] instanceof Button)
+						{
+							component[prop](component[properties[prop]]);
+						}
+						else
+						{
+							error(`Failed to set a default button for this Window. A Button "${properties[prop]}" is not defined.`, false);
+						}
+						break;
+					}
+					default:
+					{
+						component[prop](properties[prop]);
+					}
+				}
+			}
+		}
+
+		// add events
+		for(const event of Object.keys(events))
+		{
+			if(!(event in component))
+			{
+				error(`${class_name}.${event} is not valid event function for ${class_name} in your .ui.json file:\n\n${common.ui_file}`, false);
+				continue;
+			}
+
+			const func = events[event].trim();
+
+			if(func.startsWith("javascript:"))
+			{
+				try
+				{
+					component[event](new Function('e', func.substring(11).trim()).bind(this));
+				}catch(ex)
+				{
+					component[event]((...args) =>
+					{
+						alert(`${ex.constructor.name} in ${ref}.${event}() event handler:\n\n ${ex.message}`, `Error`, MessageIcon.Error);
+					});
+				}
+			}
+			else
+			{
+				component[event]((...args) =>
+				{
+					if(!(func in this)) return alert(`Missing ${event} event handler method "this.${func}(event)". Create ${func}(e){ } function.`, `Missing event handler for this.${ref} component`, MessageIcon.Error);
+
+					this[func](...args);
+				});
+			}
+		}
+	}
+
+	//endregion
+}