swing-ui 0.1.25 → 1.0.1

package/classes/ContextMenu.js

@@ -0,0 +1,141 @@
+
+import {ComponentContainer} from "./ComponentContainer.js";
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * ContextMenu UI component that extends ComponentContainer, which extends UIComponent class.
+ * ContextMenu is used to create menus that pop up when user right clicks on UI component or system tray icon.
+ * @class
+ * @global
+ * @see ComponentContainer
+ */
+export class ContextMenu extends ComponentContainer
+{
+	_parents = []; // multiple parents
+	
+	/**
+	 * ContextMenu constructor.
+	 * @example
+	 * // Usage example:
+	 * const menu = new ContextMenu();     // creates new context menu
+	 * new MenuItem("Item 1").addTo(menu); // adds menu item to context menu
+	 * new MenuItem("Item 2").addTo(menu); // adds menu item to context menu
+	 * textfield.contextMenu(menu);        // set context menu for text field
+	 */
+	constructor()
+	{
+		super("PopupMenu", (new.target === ContextMenu), ...arguments);
+		this.prop.invoker = null;
+		this.finalize(ContextMenu, ComponentContainer);
+	}
+	
+	/**
+	 * Registers, unregisters and gets a list of handler functions for the context menu popup events (when the the context menu becomes visible and hidden).
+	 *
+	 * @param {function(PopupEvent):any|null} [callback] - Event handler function that receives a {@link PopupEvent} as an argument. Pass `null` to unregister all registered callbacks.
+	 * @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 PopupEvent
+	 * @example
+	 * // event Object format:
+	 * const e = {
+	 *   target: object,        // The component that triggered the event.
+	 *   type: string,          // `show`, `hide`, `cancel`.
+	 *   invoker: Object        // UI Component that invoked the popup, or `null` if it was invoked programmatically.
+	 *   x: number,             // X position relative to invoker. Only present when invoker is not `null`.
+	 *   y: number,             // Y position relative to invoker. Only present when invoker is not `null`.
+	 *   screenX: number,       // X position relative to default screen.
+	 *   screenY: number,       // Y position relative to default screen.
+	 *   interactive: boolean,  // Indicates if the popup was triggered by user's interaction (not programmatically).
+	 * };
+	 */
+	onPopupEvents(callback, ...args)
+	{
+		return this.event("onPopupEvents", callback, args[0] ?? false);
+	}
+	
+	/**
+	 * Adds a child component to this container component.
+	 * Overrides addChild() method from UIComponent class to add component validation logic.
+	 *
+	 * @param {Object} component - UI Component that can be a child of this component.
+	 * @param {...any} [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}
+	 */
+	addChild(component, ...data)
+	{
+		const allowedTypes = [Menu, MenuItem, RadioButtonMenuItem, CheckBoxMenuItem, Separator];
+		
+		if(!allowedTypes.some(type => component instanceof type))
+		{
+			throw new Error(component.constructor.name + " cannot be added to ContextMenu");
+		}
+		
+		super.addChild(component, ...data);
+	}
+	
+	/**
+	 * Open the menu with all its parent menus or context menu.
+	 * @param {object} [position] - Example: {x: 100, y: 100}. Used to specify position where to open the ContextMenu. If invoker is specified, then position is relative to position of invoker component, otherwise it a screen position.
+	 * @param {object} [invoker] - Used to set invoker if the context menu isn't assigned to any object and you want to be able to get invoker by using "invoker" getter.
+	 * @return {ContextMenu} Returns `this` ContextMenu instance.
+	 */
+	open(position = null, invoker = null)
+	{
+		const msg = {set: "open", control: this.id, data: {}};
+		if(position != null) msg.data.position = position;
+		if(invoker instanceof UIComponent) msg.data.invoker = invoker.id;
+		
+		ui.sendToGUI(msg);
+		return this;
+	}
+	
+	/**
+	 * Returns last invoker Object that invoked the popup, or `null` if no invoker was involved.
+	 * @readonly
+	 * @type {Object|null}
+	 */
+	get invoker()
+	{
+		return this.prop.invoker;
+	}
+	
+	/**
+	 * Adds this ContextMenu to a specified parent component.
+	 *
+	 * @param {object} parent - A valid component that accepts ContextMenu. `parent` must be derived from UIComponent.
+	 * @return {ContextMenu} Returns an instance of `this` object.
+	 */
+	addTo(parent, ...args)
+	{
+		if(typeof parent !== "object" || !(parent instanceof UIComponent)) throw Error(`'parent' must be derived from UIComponent of swing-ui module.`);
+		parent.verifyComponent();
+		parent.contextMenu(this);
+		return this;
+	}
+	
+	/**
+	 * Removes this ContextMenu from all parent components or removes a specified child component from this ContextMenu.
+	 *
+	 * @param {Object} [child] - Child to be removed. When omitted, this context menu gets removed from all parent components.
+	 * @param {boolean} [recursive] - Indicates whether to also remove all child's descendents.
+	 * @return {ContextMenu} Returns an instance of `this` component.
+	 * @example
+	 * child.remove(); // Removes this context menu from it's parent components
+	 * child.remove(true); // Removes this context menu from it's parent components and all its descendants recursively
+	 * parent.remove(child); // removes child from parent container
+	 * parent.remove(child, true); // Removes child from parent container and all of child's descendants recursively
+	 */
+	remove(...args)
+	{
+		if(args.length === 0 || typeof args[0] !== "object") // removing this from parents
+		{
+			for(let parent of [...this._parents]) parent.contextMenu(null);
+		}
+		
+		// when removing child component
+		if(args.length > 0) super.removeChild(...args);
+		
+		return this;
+	}
+}

package/classes/DocumentEditor.js

@@ -0,0 +1,168 @@
+
+import zlib from "zlib"; // https://nodejs.org/api/zlib.html#class-options
+import {TextComponent} from "./TextComponent.js";
+import {ScrollableComponent} from "./ScrollableComponent.js";
+
+/**
+ * DocumentEditor UI component that extends TextComponent and ScrollableComponent, which extend UIComponent class.
+ * DocumentEditor is a text editor that can be switched to HTML mode to display or edit an HTML styled page. Only HTML 3.2 is supported. Modern tags like in HTML5 are not supported and may be ignored. HTML page can be styles with CSS but CSS support is also limited.
+ * Editing the HTML page is not great, but may be enough for basic purposes. CSS can be added to the document separately by setCSS() and addCSS() methods, or it can be embedded into the HTML content using `style` tags.
+ *
+ * For more methods for this component check UIComponent class.
+ * @class
+ * @global
+ * @see TextComponent
+ * @see ScrollableComponent
+ */
+class DocumentEditor extends TextComponent
+{
+	/**
+	 * DocumentEditor constructor. Check usage examples below
+	 *
+	 * @param {string} [content] - Initial content.
+	 * @example
+	 * let content = "<html><body><h1>This is a header</h1><p>This is a new paragraph</p></body></html>";
+	 * const editor1 = new DocumentEditor(content).html(true); // creates editor and sets content in constructor
+	 * const editor2 = new DocumentEditor().html(true).text(content); // creates editor and then sets content
+	 */
+	constructor()
+	{
+		super("DocumentEditor", (new.target === DocumentEditor), ...arguments);
+		this.finalize(DocumentEditor, TextComponent);
+	}
+	
+	/**
+	 * Sets or gets text or HTML content of the component (depending if HTML is enabled using html(boolean) method.
+	 *
+	 * @param {string} [text] - Can be plain text or HTML. HTML should be surrounded with HTML tags. Check example below.
+	 * @param {TextAction} [action] - Specific action to perform with text. Replace, append, prepend, or insert. Do not use this argument for HTML content.
+	 * @param {number} [insert_position] - Position where to insert text. Applies only if `action` argument is TextAction.Insert.
+	 * @return {string|this} Returns text or HTML if no argument is set, otherwise returns `this` component.
+	 * @example
+	 * const txt = textfield.text(); // gets text value
+	 * textfield.text("New Text"); // sets new text value
+	 * textfield.html(true).text("<html>New Text Line 1<br />New Text Line 2</html>"); // changes editor's content type to HTML and sets HTML content
+	 * textfield.text("Appended Text", TextAction.Append); // Appends new text to the end of current text
+	 * textfield.text("Inserted Text", TextAction.Insert); // Inserts at current caret position
+	 * textfield.text("Inserted Text", TextAction.Insert, textfield.caretPosition() - 50); // Inserts at specified position
+	 */
+	text()
+	{
+		if(arguments.length > 0)
+		{
+			const msg = {control: this.id, set: "text", value: String(arguments[0]), data: {action: arguments.length > 1 ? arguments[1] : TextAction.Set}};
+			if(msg.data.action === TextAction.Insert && arguments.length > 2 && Number.isSafeInteger(arguments[2])) msg.data.index = arguments[2];
+			ui.sendToGUI(msg);
+			return this;
+		}
+		else
+		{
+			let r = this.property("text", []);
+
+			// base64 decode and Gunzip value before returning
+			return zlib.gunzipSync(Buffer.from(r, "base64"), {}).toString();
+		}
+	}
+	
+	/**
+	 * Enables/Disables Word/Character line wrapping of long lines instead of scrolling horizontally.
+	 *
+	 * @param {LineWrap} [value] - LineWrap.Word, LineWrap.Character, or LineWrap.None
+	 * @return {LineWrap|DocumentEditor} If argument is passed, `this` component instance is returned, otherwise line wrap value is returned.
+	 * @see LineWrap
+	 */
+	lineWrap(...args)
+	{
+		return this.property("lineWrap", args);
+	}
+	
+	/**
+	 * Sets or gets boolean value stating if content type of the document is HTML or not. True means HTML, false means plain text.
+	 *
+	 * @param {boolean} [value] - `true` to enable HTML content type, `false` to switch to plain text.
+	 * @return {DocumentEditor|boolean} If argument is passed, `this` component instance is returned, otherwise `boolean` is returned.
+	 */
+	html(...args)
+	{
+		if(args.length > 0) args[0] = (args[0] === true);
+		return this.property("html", args);
+	}
+	
+	/**
+	 * Adds CSS styles to be applied to the HTML document without adding this CSS to the HTML content. This method should be used only when DocumentEditor's HTML content type is enabled using html(true) method. Added CSS cannot be removed separately. To remove all added CSS use setCSS("") method.
+	 *
+	 * @param {string} css - CSS content (without `style` tags).
+	 * @return {DocumentEditor}
+	 */
+	addCSS(css)
+	{
+		this.property("addCSS", [String(css)]);
+		return this;
+	}
+	
+	/**
+	 * Sets new CSS styles to be applied to the HTML document without adding this CSS to the HTML content. It replaces previously added CSS. This method can be used to remove previously added CSS by calling setCSS(""). This method should be used only when DocumentEditor's HTML content type is enabled using html(true) method.
+	 *
+	 * @param {string} css - CSS content (without `style` tags).
+	 * @return {DocumentEditor}
+	 */
+	setCSS(css)
+	{
+		this.property("setCSS", [String(css)]);
+		return this;
+	}
+	
+	/**
+	 * Sets/gets a comma separated list of HTML tags to be excluded (stripped away) from HTML document (when content type is set to HTML using html(true).
+	 *
+	 * @param {string} [tags] - A list of tags separated by comma. e.g. editor.excludedTags("hr audio video div");
+	 * @return {DocumentEditor|string}
+	 */
+	excludedTags(...args)
+	{
+		return this.property("excludedTags", args);
+	}
+	
+	/**
+	 * Sets or gets the ability to click on HTML document's hypertext links made with `a` tag to open the link in a web browser. When enabled, user can click on a hyperlink to open the link's URL in a default web browser. For that HTML content type must be enabled with html(true) method and editing should be disabled with editable(false) method.
+	 *
+	 * @param {boolean} [enabled] - `true` to enable, `false` to disable.
+	 * @return {DocumentEditor|boolean} If argument is omitted, `boolean` is returned, otherwise `this` DocumentEditor instance is returned.
+	 */
+	linksEnabled(...args)
+	{
+		if(args.length > 0) args[0] = (args[0] === true);
+		return this.property("linksEnabled", args);
+	}
+	
+	/**
+	 * Registers, unregisters, and gets an Array of event handlers for the event when user clicks on a hyperlink. It gives the ability to create a custom action for hyperlink clicks. Check for event Object format in example below.
+	 *
+	 * @param {function(LinkEvent):any} [callback] - Handler function receiving {@link LinkEvent} object. Pass `null` to unregister all handler callbacks.
+	 * @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 LinkEvent
+	 * @example
+	 * // LinkEvent format example
+	 * LinkEvent {
+	 *     target: DocumentEditor, // This component
+	 *     type: string,           // `click`, `mouseenter`, or `mouseleave`
+	 *     url: string,            // The href="" attribute of the `a` tag
+	 *     text: string,           // Text of the hyperlink
+	 *     shift: boolean,         // Indicates if Shift key was pressed when the event occurred
+	 *     ctrl: boolean,          // Indicates if Ctrl key was pressed when the event occurred
+	 *     alt: boolean,           // Indicates if Alt key was pressed when the event occurred
+	 *     modifiers: string       // Keyboard modifiers mask
+	 *     modifiersText: string   // Text representation of keyboard modifiers
+	 * }
+	 */
+	onLinkEvents(callback, ...args)
+	{
+		return this.event("onLinkEvents", callback, args[0] ?? false);
+	}
+}
+
+// Implement ScrollableComponent class methods
+Object.getOwnPropertyNames(ScrollableComponent.prototype).forEach(m=>{if(m !== 'constructor') DocumentEditor.prototype[m] = ScrollableComponent.prototype[m];});
+
+export { DocumentEditor };

package/classes/Ellipse.js

@@ -0,0 +1,76 @@
+
+import {Shape} from "./Shape.js";
+
+/**
+ * `Ellipse` shape can draw an oval (when height and width are different) or a circle (when height and width are same).
+ *
+ * Ellipse extends the {@link Shape} class.
+ * @class
+ * @global
+ * @see Shape
+ */
+export class Ellipse extends Shape
+{
+	_size = {width: 100, height: 100};
+	
+	/**
+	 * Creates an instance of Arc shape.
+	 *
+	 * @param {Stroke} [stroke=undefined] - A border of the shape.
+	 * @param {string} [background=undefined] - Color, gradient, or image background, similar to CSS. Use an empty string to remove the background.
+	 * @param {number} [opacity=1] - Opacity of the shape (0 to 1).
+	 * @param {number} [x=0] - Horizontal position from the left edge.
+	 * @param {number} [y=0] - Vertical position from the top edge.
+	 * @param {number} [width=100] - Width of the ellipse (horizontal diameter).
+	 * @param {number} [height=undefined] - Height of the ellipse (vertical diameter). If omitted, height will be same as width.
+	 */
+	constructor(stroke = undefined, background = undefined, opacity = 1, x = 0, y = 0, width = 100, height = undefined)
+	{
+		super(undefined, stroke, background, opacity, x, y);
+		this._type = "ellipse";
+		if(width == null) width = 100;
+		this._size = {width: width, height: height != null ? height : width};
+	}
+	
+	/**
+	 * Sets or gets the size of the `Ellipse` (horizontal and vertical diameter).
+	 *
+	 * @param {number|Size} width - Width of the ellipse (horizontal diameter), or a `Size` object (e.g., {width:300,height:300}).
+	 * @param {number} [height] - Height of the ellipse (vertical diameter).
+	 * @returns {Size|Ellipse} If called without parameters, current size is returned; otherwise this Ellipse object is returned.
+	 * @see Size
+	 */
+	size()
+	{
+		if(arguments.length > 0)
+		{
+			this._size = (arguments.length > 1) ? {width: arguments[0], height: arguments[1]} : arguments[0];
+			
+			if(typeof this._size !== "object") this._size = {width: this._size, height: this._size};
+			this.update("size");
+			return this;
+		}
+		else
+		{
+			return {...this._size};
+		}
+	}
+	
+	/**
+	 * 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 === "ellipse")
+		{
+			if(["all", "size"].includes(include)) shape.size = this._size;
+		}
+		
+		return shape;
+	}
+}