swing-ui 0.1.25 → 1.0.3

package/classes/TextShape.js

@@ -0,0 +1,123 @@
+
+import {Shape} from "./Shape.js";
+
+/**
+ * TextShape is used to draw text as a shape. It can also have a {@link Stroke}, background, and everything like other shapes have.
+ *
+ * In Text shape you can also specify font parameters, like name, size, underlines, italic, bold, strikethrough and more. Check out {@link FontFamily} enum for generic font family names that can be used for cross-platform compatibility.
+ *
+ * @class
+ * @global
+ * @see Shape
+ */
+export class TextShape extends Shape
+{
+	_text = "";
+	_font = {size: 13, name: FontFamily.SansSerif};
+	
+	/**
+	 * Constructor of Text shape. Color, Gradient, or background image are specified in "background" argument, because it's a Shape.
+	 *
+	 * @param {string} text - Text to be drawn as shape
+	 * @param {Font} [font=undefined] - Font object, such as {size: 13, name: "sans-serif", ...}.
+	 * @param {Stroke} [stroke=null] - Stroke object.
+	 * @param {string} [background="#000000"] - Background string, CSS style. See {@link Shape#background} for details.
+	 * @param {number} [opacity=1] - Opacity of the shape. Valid value is a decimal between 0 - 1.
+	 * @param {number} [x=0] - X position of top-left corner of text
+	 * @param {number} [y=0] - Y position of top-left corner of text
+	 * @see Font
+	 * //@param {number} [width] - Width of the text bounding box. null means all in one line. No wrapping.
+	 * //@param {number} [height] - Height of the text bounding box. null means auto-detect, without limit.
+	 */
+	constructor(text, font = undefined, stroke = null, background = "#000000", opacity = 1, x = 0, y = 0)
+	{
+		super(undefined, stroke, background, opacity, x, y);
+		this._type = "text";
+		this._text = text;
+		if(!(typeof font === "object")) font = {size: 13, name: "sans-serif"}; // set default font
+		if(font !== null) this._font = font;
+		this.background(background);
+		this.opacity(opacity);
+		this.position(x, y);
+	}
+	
+	/**
+	 * Sets new text to the shape. this will recreate the graphics of the shape for the new text.
+	 *
+	 * @param {string} text - New text for the shape.
+	 * @return {string|TextShape} If called without parameters, current text value is returned; otherwise this `Text` shape object is returned.
+	 */
+	text()
+	{
+		if(arguments.length > 0)
+		{
+			const new_text = String(arguments[0]);
+			if(new_text !== this._text) // update if different
+			{
+				this._text = new_text;
+				this.update("text");
+			}
+			return this;
+		}
+		
+		return this._text;
+	}
+	
+	/**
+	 * Gets or sets the font used for the `Text` shape. See the example for font object format.
+	 *
+	 * @param {Font} [font] - Font object.
+	 * @return {TextShape|Font}
+	 * @see Font
+	 * @example
+	 * textShape.font({name: "sans-serif", size: 14, italic: true}); // Sets new font.
+	 * const font = textShape.font(); // gets component's font
+	 *
+	 * // Full list of supported font properties:
+	 * const font = {
+	 *     name: string,           // Font name or family name from {@link FontFamily} (e.g., "sans-serif")
+	 *     size: number,           // Font size in pixels
+	 *     bold: boolean,          // Whether the text is bold
+	 *     italic: boolean,        // Whether the text is italic
+	 *     underlined: boolean,    // Whether the text is underlined
+	 *     strikethrough: boolean, // Whether the text has a strikethrough
+	 *     direction: string,      // Text direction: "ltr" or "rtl"
+	 *     kerning: boolean,       // Enable or disable kerning
+	 *     ligatures: boolean,     // Enable or disable font ligatures
+	 *     tracking: number        // Letter spacing adjustment: -1, 0 (default), or 1
+	 * };
+	 * @see Font
+	 * @see FontFamily
+	 */
+	font()
+	{
+		if(arguments.length > 0)
+		{
+			if(typeof arguments[0] !== "object") return this;
+			this._font = arguments[0];
+			this.update("font");
+			return this;
+		}
+		
+		return this._font;
+	}
+	
+	/**
+	 * 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(what = "all")
+	{
+		let shape = super.toObject(what);
+		
+		if(this._type === "text")
+		{
+			if(["all", "text"].includes(what)) shape.text = this._text;
+			if(["all", "font"].includes(what)) shape.font = this._font;
+		}
+		
+		return shape;
+	}
+}

package/classes/ToggleButton.js

@@ -0,0 +1,147 @@
+
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * ToggleButton UI component that is similar to a `Button` component, but can be selected.
+ * @class
+ * @global
+ */
+export class ToggleButton extends UIComponent
+{
+	/**
+	 * ToggleButton constructor.
+	 *
+	 * @param {string} [text] - Button text
+	 * @example
+	 * this.button1 = new ToggleButton().text("Click Me");
+	 * this.button2 = new ToggleButton("Click Me");
+	 */
+	constructor()
+	{
+		if(arguments.length > 0)
+		{
+			super("ToggleButton", (new.target === ToggleButton), arguments[0]);
+		}
+		else
+		{
+			super("ToggleButton", (new.target === ToggleButton));
+		}
+		
+		this.finalize(ToggleButton);
+	}
+	
+	/**
+	 * Sets/Gets selection state of the toggle button.
+	 *
+	 * @param {boolean} [selected] - `true` to select, `false` to deselect the toggle button.
+	 * @return {boolean|ToggleButton} If called without arguments, returns `boolean` value, otherwise returns `this` ToggleButton instance.
+	 */
+	selected()
+	{
+		return this.property("selected", arguments.length > 0 ? [arguments[0] === true] : []);
+	}
+	
+	/**
+	 * Sets/Gets whether the toggle button can be selected by the user.
+	 *
+	 * @param {boolean} [selectable] - `true` to allow selection, `false` to prevent the toggle button from being selected.
+	 * @return {boolean|ToggleButton} If called without arguments, returns `boolean` value, otherwise returns `this` ToggleButton instance.
+	 * @see ToggleButton#selected
+	 */
+	selectable()
+	{
+		const args = arguments;
+		if(args.length > 0) args[0] = (args[0] === true); // ensure boolean type
+		return this.property("selectable", args);
+	}
+
+	/**
+	 * Sets or gets a value of this component.
+	 * @param {*} [value] - Value to be held by this component
+	 * @return {ToggleButton|*} If setting a value, then an instance of `this` component is returned, otherwise current value is returned.
+	 */
+	value()
+	{
+		return this.property("value", arguments);
+	}
+
+	/**
+	 * Gets or sets the selected value within this ToggleButton group.
+	 *
+	 * If a value is provided, selects a ToggleButton within the group that matches the given value (including this one).
+	 *
+	 * @param {number|string} [value] - Value to select within the group.
+	 * @return {ToggleButton|number|string|null} If value is provided, an instance of `this` object is returned. If no argument is provided, a value of the currently selected radio button in the group is returned, or `null`, if no button is selected or selected button doesn't have a value.
+	 */
+	selectedValue()
+	{
+		return this.property("selectedValue", arguments);
+	}
+
+	/**
+	 * Adds this ToggleButton to the group of another ToggleButton while abandoning current group, or removes it from its current group and creates its own when you pass `null`.
+	 *
+	 * - Call without parameters to get an Array of all components in its group.
+	 * - Pass another ToggleButton to join its group.
+	 * - Pass `null` to leave the current group (if any) and create its own group.
+	 *
+	 * @param {ToggleButton|null} [component] - A ToggleButton to join, or `null` to leave the current group. Omit to get the grouped ToggleButton components.
+	 * @returns {ToggleButton|ToggleButton[]} This ToggleButton, for chaining when called with parameter, otherwise an Array of all ToggleButton components in its group.
+	 */
+	group(...args)
+	{
+		if(args.length > 0)
+		{
+			if(args[0] !== null && !(args[0] instanceof this.constructor)) throw new Error(`Invalid value passed to ${this.constructor.name}.group(). ${this.constructor.name} component or NULL is expected.`);
+			return this.property("group", [args[0] !== null ? args[0].id : null]);
+		}
+		else
+		{
+			let _items = this.property("group", []);
+
+			for(let i in _items) _items[i] = UIComponent.get(_items[i]);
+
+			return _items;
+		}
+	}
+
+	/**
+	 * Deselect all RadioButton elements grouped with this element.
+	 *
+	 * @return {RadioButton} Returns `this` component.
+	 */
+	clearSelection()
+	{
+		ui.sendToGUI({control: this.id, set: "clearSelection"});
+		return this;
+	}
+
+	/**
+	 * Sets or gets an action command. This command is specified in event object for onAction(e => {alert(e.command);}) event handler.
+	 * Default value of action command for a Button is it's initial text.
+	 *
+	 * @param {string} [command] (Optional)
+	 * @return {string|Button} If called without arguments, returns `number` value, otherwise returns `this` Button instance.
+	 * @example
+	 * const button = new Button("Activate").addTo(window).center();
+	 * button.command("Activate Motor 1");
+	 * button.onAction(e => {
+	 *    alert(e.command); // shows a dialog window with a message "Activate Motor 1" when button is clicked.
+	 * });
+	 */
+	command(...args)
+	{
+		if(args.length > 0 && typeof args[0] !== "string") args[0] = String(args[0]); // enforce string type
+		return this.property("actionCommand", args);
+	}
+	
+	/**
+	 * Returns current size of an icon, or `null` when no icon has been set or icon failed to load.
+	 * @readonly
+	 * @type {Size|null}
+	 */
+	get iconSize()
+	{
+		return this.property("iconSize", []);
+	}
+}

package/classes/ToolBar.js

@@ -0,0 +1,120 @@
+
+import {ComponentContainer} from "./ComponentContainer.js";
+
+/**
+ * A toolbar component that is usually used at the top of window and can hold {@link Label}, {@link Button}, {@link TextField}, {@link ComboBox}, and a {@link Separator} to display useful tools for a user.
+ *
+ * Toolbar can be draggable and can be detached and displayed in a separate dedicated window. It can also be in horizontal (default) and vertical orientation.
+ *
+ * ToolBar extends ComponentContainer, which extends UIComponent.
+ *
+ * @class
+ * @global
+ */
+export class ToolBar extends ComponentContainer
+{
+	/**
+	 * Create an instance of ToolBar component object.
+	 */
+	constructor()
+	{
+		super("ToolBar", (new.target === ToolBar));
+		
+		this.finalize(ToolBar, ComponentContainer);
+	}
+	
+	/**
+	 * Sets of gets whether the ToolBar can be detached from the Window it was added to.
+	 *
+	 * @param {boolean} [detachable] - `true` to enable detaching, `false` to disable.
+	 * @return {boolean|ToolBar} If no parameters were passed, current value is returned, otherwise `this` Toolbar component is returned for method chaining.
+	 */
+	detachable()
+	{
+		return this.property("detachable", arguments);
+	}
+	
+	/**
+	 * Sets or gets boolean whether the toolbar is attached to main Window. Has no affect if not attached to a Window yet.
+	 *
+	 * @param {boolean} [attached] - `true` to attach, `false` to detach from Window component the ToolBar is added to.
+	 * @param {{x:number, y:number}} [floating_position] - Position on screen where toolbar should float {x:number, y:number}.
+	 * @return {boolean|ToolBar} If no parameters were passed, current state is returned; otherwise `this` Toolbar component is returned for method chaining.
+	 */
+	attached(...args)
+	{
+		return this.property("attached", args.length === 0 ? [] : [{value: (args[0] !== false), location: args.length > 1 ? {x: args[1].x ?? 0, y: args[1].y ?? 0} : undefined}]);
+	}
+	
+	/**
+	 * Sets or gets vertical or horizontal orientation of the ToolBar.
+	 *
+	 * @param {Orientation} [orientation] - One of these values: Orientation.Horizontal (default) or Orientation.Vertical
+	 * @return {Orientation|ToolBar} If no parameters were passed, current orientation is returned; otherwise `this` Toolbar component is returned for method chaining.
+	 * @see Orientation
+	 */
+	orientation(...args)
+	{
+		return this.property("orientation", args);
+	}
+	
+	/**
+	 * Sets or gets a padding size between edge of the component and items inside it, and spacing between items.
+	 *
+	 * @param {number} padding - Padding size in pixels.
+	 * @return {number|ToolBar} If no parameters were passed, current padding is returned; otherwise `this` Toolbar component is returned for method chaining.
+	 */
+	padding(...args)
+	{
+		if(args.length > 0) args[0] = parseInt(args[0]);
+		return this.property("padding", args);
+	}
+	
+	/**
+	 * Set or get alignment of components within toolbar.
+	 *
+	 * @param {string} [alignment] - "leading|trailing|left|center|right"
+	 * @return {string|ToolBar} If no parameters were passed, current alignment is returned; otherwise `this` Toolbar component is returned for method chaining.
+	 */
+	alignment(...args)
+	{
+		if(args.length > 0 && typeof args[0] !== "string") throw new TypeError(`Invalid alignment argument type. String expected, but received '${typeof args[0]}'.`);
+		return this.property("alignment", args);
+	}
+	
+	/**
+	 * Add an invisible spacer of specified width and height.
+	 *
+	 * @param {number} width - Width of the spacer block
+	 * @param {number} height - Height of the spacer block
+	 * @return {ToolBar} Returns `this` ToolBar component for method chaining.
+	 */
+	addSpacer(width, height)
+	{
+		return this.property("addSpacer", [{width: width, height: height}]);
+	}
+	
+	/**
+	 * Gets, registers or unregisters a docking event handler function. This event handler is called when the ToolBar gets attached/detached.
+	 *
+	 * @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 {ToolBar|function[]} An array of handler functions if no arguments are passed, otherwise `this` component for method chaining.
+	 *
+	 * @example
+	 * // Event object format:
+	 * const e = {
+	 *   target: object,                        // The ToolBar component that triggered the event.
+	 *   type: string,                          // "attached", "detached".
+	 *   interactive: boolean                   // Only when type is "update". `true` when update was made by the user interacting with the GUI. `false` when update was made programmatically.
+	 *   orientation: Orientation               // current orientation
+	 *   location: string                       // "top", "bottom", "left", "right". Only when `e.interactive` is `true`.
+	 *   mouseX: number                         // Mouse X position relative to Window's content area.  Only when `e.interactive` is `true`.
+	 *   mouseY: number                         // Mouse Y position relative to Window's content area.  Only when `e.interactive` is `true`.
+	 * };
+	 */
+	onDockEvents(callback, ...args)
+	{
+		return this.event("onDockEvents", callback, args[0] ?? false);
+	}
+}

package/classes/TrayIcon.js

@@ -0,0 +1,54 @@
+
+import {UIComponent} from "./UIComponent.js";
+
+/**
+ * TrayIcon is a system icon usually displayed in a tray of icons for applications running or capable of running in the background.
+ *
+ * TrayIcon component is able to show system notification messages, have context menu and show tooltip text on mouse hover.
+ *
+ * @class
+ * @global
+ * @example <h2>Create new TrayIcon:</h2>
+ * const icon = new TrayIcon("/path/to/icon.png").tooltip("New App Icon").contextMenu(existing_context_menu).show();
+ *
+ * @example <h2>Set an event handler:</h2>
+ * icon.onMouseEvents(e => {
+ *     console.log(`${e.clicks} ${e.type}`);
+ * })
+ * .onAction(e => {
+ *     console.log("System tray icon action was performed.");
+ * });
+ *
+ * @example <h2>Show system message:</h2>
+ * icon.showNotification(`Warning Sample`, `This is a sample message`, MessageIcon.Warning);
+ *
+ * @example <h2>hide and show the icon:</h2>
+ * icon.hide(); // or icon.visible(false);
+ *
+ * icons.show(); // or icon.visible(true);
+ */
+export class TrayIcon extends UIComponent
+{
+	/**
+	 * Slider TrayIcon. Creates an instance of TrayIcon UI component.
+	 * @param {string} icon - Icon image (relative/absolute path or base64 encoded image string).
+	 */
+	constructor(icon)
+	{
+		super("SystemTrayIcon", (new.target === TrayIcon), icon);
+		this.finalize(TrayIcon);
+	}
+	
+	/**
+	 * Displays system notification.
+	 *
+	 * @param {string} title - Title of the notification message
+	 * @param {string} message - The message body
+	 * @param {MessageIcon} [icon=MessageIcon.Info] - One of the values: MessageIcon.Info, MessageIcon.Warning, MessageIcon.Info, or `null` to not show any icon.
+	 * @return {TrayIcon} Returns `this` TrayIcon component for method chaining.
+	 */
+	showNotification(title, message, icon = MessageIcon.Info)
+	{
+		return this.property("showNotification", [{title: String(title), message: String(message), icon: parseInt(icon)}]);
+	}
+}