swing-ui 0.1.25 → 1.0.3

package/enums.js

@@ -0,0 +1,298 @@
+
+/**
+ * A keyboard shortcut binding scope. Used to set when a keyboard shortcut should emit a KeyEvent for onShortcutAction() event handler using a {@link UIComponent#shortcuts|shortcuts()} method.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Focused - When the component has focus (default for non-container components).
+ * @property {number} Ancestor - When any child or their children have a focus (default for container components, other than Window).
+ * @property {number} Window - When component is in focused window (default for Window component).
+ * @see UIComponent#shortcuts
+ * @see UIComponent#onShortcut
+ */
+export const ShortcutScope = Object.freeze({Focused: 0, Ancestor: 1, Window: 2});
+
+/**
+ * Enum for drag and drop actions.
+ * Used with `dragAction()` and `dropAction()`.
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} None - No action.
+ * @property {string} Copy - Copy action.
+ * @property {string} Move - Move action.
+ * @property {string} CopyOrMove - Copy or move action.
+ * @property {string} Link - Link action.
+ * @see UIComponent#dragAction
+ * @see UIComponent#dropAction
+ * @example
+ * list.dragAction(DragDropAction.CopyOrMove);
+ * list.dropAction(DragDropAction.CopyOrMove);
+ */
+export const DragDropAction = Object.freeze({None: "None", Copy: "Copy", Move: "Move", CopyOrMove: "CopyOrMove", Link: "Link"});
+
+/**
+ * Used with dropMode() in Table, List, and Tree
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} On - Drop on items.
+ * @property {string} Insert - Insert between items
+ * @property {string} OnOrInsert - Drop on items and between items
+ * @see {@link List#dropMode|List.dropMode()}
+ * @see {@link Table#dropMode|Table.dropMode()}
+ * @see {@link Tree#dropMode|Tree.dropMode()}
+ * @example
+ * table.dropMode(DropMode.OnOrInsert);
+ */
+export const DropMode = Object.freeze({On: "On", Insert: "Insert", OnOrInsert: "OnOrInsert"});
+
+/**
+ * Enum for mouse actions.
+ * Used with `ui.mouseAction(action, button)`.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Press - Mouse button press.
+ * @property {number} Release - Mouse button release.
+ * @property {number} Click - Single click.
+ * @property {number} DoubleClick - Double click.
+ * @property {number} VerticalScroll - Vertical wheel scroll.
+ * @property {number} HorizontalScroll - Horizontal wheel scroll.
+ * @see SwingUI#mouseAction
+ * @example <h2>Performing a mouse click:</h2>
+ * ui.mouseAction(MouseAction.Click, MouseButton.Left);
+ */
+export const MouseAction = Object.freeze({Press: 0, Release: 1, Click: 2, DoubleClick: 3, VerticalScroll: 4, HorizontalScroll: 5});
+
+/**
+ * Enum for mouse buttons.
+ * Compare to `mouseEvent.button` on mouse events or use with `ui.mouseAction(action, button)`.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Left - Left mouse button.
+ * @property {number} Right - Right mouse button.
+ * @property {number} Middle - Middle mouse button.
+ * @see SwingUI#mouseAction
+ * @see UIComponent#onMouseEvents
+ * @example <h2>Checking if right mouse button was clicked:</h2>
+ * if(mouseEvent.button === MouseButton.Right)
+ * {
+ *     console.log("Right click);
+ * }
+ * @example <h2>Performing a mouse click:</h2>
+ * ui.mouseAction(MouseAction.Click, MouseButton.Left);
+ */
+export const MouseButton = Object.freeze({Left: 1, Right: 3, Middle: 2});
+
+/**
+ * Keyboard key actions to be performed on the computer. Use it only with `ui.keyboardAction(action, value)` to perform key actions.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Press - Key press.
+ * @property {number} Release - Key release.
+ * @property {number} Type - Key typed (typed character input).
+ * @see SwingUI#keyboardAction
+ * @example <h2>Performing a key type action:</h2>
+ * ui.keyboardAction(KeyAction.Type, "A");
+ */
+export const KeyAction = Object.freeze({Press: 0, Release: 1, Type: 2});
+
+/**
+ * Enum for standard message dialog icons. Used in `alert()`, `dialog()` and `TrayIcon.showNotification()`.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Error - Error icon.
+ * @property {number} Info - Information icon.
+ * @property {number} Warning - Warning icon.
+ * @property {number} Question - Question icon.
+ * @see alert
+ * @see dialog
+ * @see TrayIcon#showNotification
+ * @example
+ * alert("This file doesn't exist!", "File Absent", MessageIcon.Warning);
+ */
+export const MessageIcon = Object.freeze({Error: 0, Info: 1, Warning: 2, Question: 3});
+
+/**
+ * Enum for selection modes in UI components like Table, List, Tree. Used with `selectionMode()` to set of get a selection mode of a list of items or rows.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Single - Single item selection.
+ * @property {number} Range - Range selection (shift-click).
+ * @property {number} Multiple - Multiple selection (ctrl/cmd-click).
+ * @see Table#selectionMode
+ * @see List#selectionMode
+ * @see Tree#selectionMode
+ * @example
+ * table.selectionMode(SelectionMode.Single);
+ */
+export const SelectionMode = Object.freeze({Single: 0, Range: 1, Multiple: 2});
+
+/**
+ * An enum for generic font family names to use instead of a font name that may not be installed on target operating systems.
+ * Use with `component.font()`, `Text()` shape, `font` property of a List item, Tree item, ComboBox item, Table column, and everywhere else where font can be set.
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} Serif - Proportional font with small decorative strokes at the ends of letters (e.g., Times New Roman, Georgia, Garamond, Cambria.).
+ * @property {string} SansSerif - Proportional font without decorative strokes; clean and modern (e.g., Arial, Helvetica, Verdana, Calibri, Open Sans).
+ * @property {string} Monospaced - Fixed-width font where every character has the same width (e.g., Courier New, Consolas, Lucida Console, Menlo).
+ * @property {string} Cursive - Flowing, handwritten-style font (e.g., Brush Script, Comic Sans MS, Pacifico, Lobster).
+ * @property {string} System - The system UI font provided by the operating system. (e.g., Segoe UI (Windows), San Francisco (macOS/iOS), Roboto (Android/Linux)).
+ * @property {string} Fantasy - Decorative or themed font (e.g., Impact, Papyrus, Jokerman, Copperplate).
+ * @see UIComponent#font
+ * @see Text
+ * @example <h2>Setting component font:</h2>
+ * textarea.font({name: FontFamily.SansSerif});
+ *
+ * @example <h2>Setting Text shape font:</h2>
+ * let text = new TextShape("Hello World", {name: FontFamily.Fantasy, size: 30});
+ */
+export const FontFamily = Object.freeze({Serif: "serif", SansSerif: "sans-serif", Monospaced: "monospace", Cursive: "cursive", System: "system-ui", Fantasy: "fantasy"});
+
+/**
+ * Enum for data types used with drag and drop.
+ * Used with `dragDataType()`, `dropDataType()`, and to check if certain data type was dragged onto component.
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} None - No data.
+ * @property {string} All - Accept any type. Used only for dropDataType().
+ * @property {string} Text - Plain text.
+ * @property {string} HTML - HTML content.
+ * @property {string} Image - Image data.
+ * @property {string} Files - Files copied to system clipboard or dragged/dropped.
+ * @property {string} URIList - List of URIs.
+ * @property {string} URL - A single URL string.
+ * @property {string} JSON - JSON-encoded data.
+ * @property {string} TextEncoding - Text encoding used to encode the Text and/or HTML values.
+ * @property {string} Components - UI components (`component/*`).
+ * @example <h2>Sets the type of data list items represent when dragged:</h2>
+ * list.dragDataType(DataType.Files);
+ * @example <h2>Sets the type of data Table component accepts:</h2>
+ * table.dropDataType([DataType.Files, DataType.URIList, DataType.URL]);
+ * @example <h2>Check if expected data type was dragged onto Label:</h2>
+ * label.dropAction(DragDropAction.CopyOrMove).dropDataType(DataType.Files).onDropEvents(e => {
+ *  if(e.type === "drop" && Array.isArray(e.data[DataType.Filest]))
+ *  {
+ *      // set first file as label's icon image
+ *      e.target.icon(e.data[DataType.Files][0]);
+ *  }
+ * });
+ */
+export const DataType = Object.freeze({None: "None", All: "All", Text: "Text", HTML: "HTML", Image: "Image", Files: "Files", URIList: "URIList", URL: "URL", JSON: "JSON", Components: "component/*"});
+
+/**
+ * Enum for actions on text components (TextField, TextArea, etc.). To be used in text() method.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Set - Replace all text.
+ * @property {number} Prepend - Add text at the beginning.
+ * @property {number} Append - Add text at the end.
+ * @property {number} Insert - Insert at current caret position.
+ * @property {number} ReplaceSelection - Replace selected text.
+ * @see UIComponent#text
+ * @example <h2>Appending text to TextArea component:</h2>
+ * let textarea = new TextArea("Hello").text(" World!", TextAction.Append);
+ * // text area will contain text "Hello World!"
+ */
+export const TextAction = Object.freeze({Set: 0, Prepend: 1, Append: 2, Insert: 3, ReplaceSelection: 4});
+
+/**
+ * Enum for available mouse cursors.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Default - Default cursor.
+ * @property {number} Crosshair - Crosshair.
+ * @property {number} Text - Text input cursor.
+ * @property {number} Wait - Wait/busy cursor.
+ * @property {number} ResizeSW - Resize south-west.
+ * @property {number} ResizeSE - Resize south-east.
+ * @property {number} ResizeNW - Resize north-west.
+ * @property {number} ResizeNE - Resize north-east.
+ * @property {number} ResizeN - Resize north.
+ * @property {number} ResizeS - Resize south.
+ * @property {number} ResizeW - Resize west.
+ * @property {number} ResizeE - Resize east.
+ * @property {number} Hand - Pointing hand.
+ * @property {number} Move - Move cursor.
+ * @see UIComponent#cursor
+ * @example <h2>Sets "Wait" cursor to Panel component:</h2>
+ * panel.cursor(Cursor.Wait);
+ */
+export const Cursor = Object.freeze({Default: 0, Crosshair: 1, Text: 2, Wait: 3, ResizeSW: 4, ResizeSE: 5, ResizeNW: 6, ResizeNE: 7, ResizeN: 8, ResizeS: 9, ResizeW: 10, ResizeE: 11, Hand: 12, Move: 13});
+
+/**
+ * Enum for component orientation, such as Slider or Toolbar.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} Horizontal - Horizontal orientation.
+ * @property {number} Vertical - Vertical orientation.
+ * @see SplitView#orientation
+ * @see ToolBar#orientation
+ * @example <h2>Setting orientation to a component:</h2>
+ * toolbar.orientation(Orientation.Vertical);
+ */
+export const Orientation = Object.freeze({Horizontal: 0, Vertical: 1});
+
+/**
+ * Border style enum. Use in a border object..
+ *
+ * @readonly
+ * @global
+ * @enum {string}
+ * @property {string} None - No border.
+ * @property {string} Line - Solid line.
+ * @property {string} Dashed - Dashed border.
+ * @property {string} Metal - Metallic style.
+ * @property {string} EtchedRaised - Etched raised border.
+ * @property {string} EtchedLowered - Etched lowered border.
+ * @property {string} BevelRaised - Bevel raised border.
+ * @property {string} BevelLowered - Bevel lowered border.
+ * @property {string} SoftRaised - Soft raised border.
+ * @property {string} SoftLowered - Soft lowered border.
+ * @see UIComponent#border
+ * @example <h2>Setting a new border:</h2>
+ * let border = {style: BorderStyle.Dashed, size: 2, color: "#002288"}
+ * panel.border(border);
+ */
+export const BorderStyle = Object.freeze({None: "none", Line: "line", Dashed: "dashed", Metal: "metal", EtchedRaised: "etched_raised", EtchedLowered: "etched_lowered", BevelRaised: "bevel_raised", BevelLowered: "bevel_lowered", SoftRaised: "soft_raised", SoftLowered: "soft_lowered"});
+
+/**
+ * Enum for word wrapping styles.
+ * Used with `lineWrap()` method in TextArea and DocumentEditor to control how text is wrapped.
+ *
+ * @readonly
+ * @global
+ * @enum {number}
+ * @property {number} None - Disable line wrapping.
+ * @property {number} Word - Wrap line when a full word doesn't fit.
+ * @property {number} Character - Wrap line when a character doesn't fit.
+ * @see TextArea#lineWrapping
+ * @see DocumentEditor#lineWrapping
+ * @example <h2>Setting line wrapping style:</h2>
+ * textarea.lineWrap(LineWrap.Word);
+ */
+export const LineWrap = Object.freeze({None: 0, Word: 1, Character: 2});
+

package/fonts.conf

@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
+<fontconfig>
+
+  <!-- This file is required for ffmpeg to draw text -->
+
+  <!-- Windows font directory -->
+  <dir>C:/Windows/Fonts</dir>
+
+  <!-- Linux font directories -->
+  <dir>/usr/share/fonts</dir>
+  <dir>/usr/local/share/fonts</dir>
+  <dir>~/.fonts</dir>
+
+  <!-- macOS font directories -->
+  <dir>/System/Library/Fonts</dir>
+  <dir>/Library/Fonts</dir>
+  <dir>~/Library/Fonts</dir>
+
+  <!-- Cache directory -->
+  <cachedir>/tmp/fontconfig/cache</cachedir>
+
+  <!-- Default font fallback -->
+  <match target="pattern">
+    <test name="family" qual="any">
+      <string>sans-serif</string>
+    </test>
+    <edit name="family" mode="prepend">
+      <string>Arial</string>
+    </edit>
+  </match>
+</fontconfig>

package/functions.js

@@ -0,0 +1,254 @@
+/**
+ * Utility Functions
+ */
+
+import "./classes/UIComponent.js";
+import {UIComponent} from "./classes/UIComponent.js";
+
+/**
+ * Displays a dialog windows with error message and error icon.
+ *
+ * @param {string|Error} message - Error message to display or Error object to display stack trace.
+ * @param {boolean|Error} [show_stack_trace=true] - Whether to show stack trace to be able to trace the error (applies only when first parameter is not an Error object).
+ * @return {void} Does not return a value
+ * @global
+ * @example <h2>Showing an error message only:</h2>
+ * error("Invalid parameters passed.", false);
+ *
+ * @example <h2>Showing an error message with a stack trace:</h2>
+ * error("Invalid parameters passed.");
+ *
+ * @example <h2>Showing an error message by passing an Error object:</h2>
+ * try
+ * {
+ *     // some code that may throw an error
+ * }
+ * catch(ex)
+ * {
+ *     error(ex);
+ * }
+ *
+ */
+export function error(message, show_stack_trace = true)
+{
+	if(message instanceof Error)
+	{
+		message = show_stack_trace ? message.stack.toString() : message.message;
+	}
+	else if(show_stack_trace)
+	{
+		message +=  "\r\n" + (show_stack_trace instanceof Error ? show_stack_trace.stack.toString() : new Error().stack.toString());
+	}
+
+	if(typeof ui !== "undefined")
+	{
+		if(message instanceof Error) message = message.stack;
+		alert(message, "JavaScript Error", 0);
+	}
+	else
+	{
+		console.error(message);
+	}
+}
+
+/**
+ * Returns a text representation of passed variable. Similar to JSON.stringify().
+ *
+ * @internal
+ * @ignore
+ * @global
+ * @param {any} variable - Any variable to be converted to a string representation
+ * @return {string} Serialized object as a String
+ */
+export function stringify(variable)
+{
+	const cache = new Set();
+
+	function recursiveStringify(value, indent = 0)
+	{
+		const ind_str = "    ";
+
+		if(value === undefined)
+		{
+			return ind_str.repeat(indent) + "UNDEFINED";
+		}
+		else if(value === null)
+		{
+			return ind_str.repeat(indent) + "NULL";
+		}
+		else if(typeof value === "string")
+		{
+			return `"${value}"`;
+		}
+		else if(typeof value === "function")
+		{
+			return "Function()"; //ind_str.repeat(indent) + value.toString();
+		}
+		if(typeof value === "object")
+		{
+			if(cache.has(value))
+			{
+				return ind_str.repeat(indent) + value.constructor.name + "{} [Circular]";
+			}
+			cache.add(value);
+
+			if(Array.isArray(value))
+			{
+				return value.length === 0 ? `[]` : `[\n` + ind_str.repeat(indent) + `${value.map(item => recursiveStringify(item, indent + 1)).join(",\n" + ind_str.repeat(indent))}\n${ind_str.repeat(Math.max(0, indent - 1))}]\n`;
+			}
+			else if(value.constructor && value.constructor.name !== "Object")
+			{
+				// Handles custom classes or instances of built-in classes (like Date)
+				const className = value.constructor.name;
+				const props = Object.keys(value).map(key => ind_str.repeat(indent) + `${key}: ${recursiveStringify(value[key], indent + 1)}`);
+				return props.length === 0 ? `${className}{}` : `${className} {\n${props.join("\n")}\n${ind_str.repeat(Math.max(0, indent - 1))}}`;
+			}
+			else
+			{
+				// Handles plain objects
+				const props = Object.keys(value).map(key => ind_str.repeat(indent) + `${key}: ${recursiveStringify(value[key], indent + 1)}`);
+				return `{\n${props.join("\n")}\n${ind_str.repeat(Math.max(0, indent - 1))}}`;
+			}
+		}
+
+		// Handles primitives, strings, and everything else
+		return JSON.stringify(value);
+	}
+
+	return recursiveStringify(variable);
+}
+
+/**
+ * Displays a dialog window with a specified error message and an error icon.
+ *
+ * @param {string} message - A message to be displayed in the dialog window
+ * @param {string} [title="Message"] - Dialog window title bar text
+ * @param {MessageIcon} [icon=MessageIcon.Info] - Icon to show in the dialog window.
+ *
+ * Valid value are:
+ *  - MessageIcon.Error
+ *  - MessageIcon.Info
+ *  - MessageIcon.Warning
+ *  - MessageIcon.Question
+ *
+ * @param {Window} [ownerWindow=null] - If set, the message dialog window will attempts to be centered at specified window
+ * @return {void} Does not return a value
+ * @global
+ *
+ * @example <h2>Simple usage with only one parameter:</h2>
+ * alert("File name is invalid. Please try again");
+ *
+ * @example <h2>Usage example when passing all parameters:</h2>
+ * alert("File name is invalid. Please try again","Invalid File", MessageIcon.Warning, this);
+ */
+export function alert(message, title = "Message", icon = 1, ownerWindow = null)
+{
+	if(ownerWindow instanceof globalThis.UIComponent) ownerWindow = ownerWindow.window;
+	
+	ui.showMessage(message, title, icon, ownerWindow);
+}
+
+/**
+ * Requests user for text input in a dialog window. Returns a string as user's input or undefined when user declined to input.
+ *
+ * @param {string} message - Message to user about this text input.
+ * @param {string} [default_value=""] - Default string that will be already present in the dialog window.
+ * @param {Window} [ownerWindow=null] - Window that will be overlaid by the dialog window.
+ * @returns {string|undefined} Returns user provided string, or `undefined` if user canceled input.
+ * @global
+ * @example
+ * let response = prompt("Please enter your name:", "John Doe", this);
+ * console.log("You entered: " + response);
+ */
+export function prompt(message, default_value = "", ownerWindow = null)
+{
+	const req = {
+		java: "showInputDialog",
+		message: message,
+		default: default_value
+	};
+	
+	if(ownerWindow instanceof globalThis.Window)
+	{
+		req.owner = ownerWindow.id;
+	}
+	else if(ownerWindow instanceof globalThis.UIComponent)
+	{
+		ownerWindow = ownerWindow.window;
+		if(ownerWindow instanceof globalThis.Window) req.owner = ownerWindow.id;
+	}
+	
+	return ui.sendToGUI(req, function(r){return r.value;}, true);
+}
+
+/**
+ * Displays a confirmation dialog to user and returns user's response as boolean.
+ *
+ * @param {string} message - Message to display to user
+ * @param {Window} [window=null] - Window which dialog window will overlay. If omitted, last created visible Window that's not PopUp will be used.
+ * @return {boolean} Returns `true` if user confirms the message, or `false` otherwise.
+ * @global
+ * @example
+ * if(confirm("Delete this file?", this))
+ * {
+ *     // delete code
+ * }
+ */
+export function confirm(message, window = null)
+{
+	// find first visible window
+	if(window == null)
+	{
+		window = UIComponent.getVisibleWindow();
+	}
+	else if(window instanceof UIComponent) window = window.window;
+	if(window == null) throw new Error("Window must be specified where to show confirmation dialog, or at least one window must be visible.");
+	
+	return window.confirm(message);
+}
+
+/**
+ * Shows a custom dialog window that allows the user to respond by clicking one of provided buttons.
+ *
+ * @param {string} message - String message to user. It can be plain text or HTML.
+ * @param {string} [title=""] - Dialog window title shown in the title bar of the window
+ * @param {string[]} [buttons=["OK","Cancel"]] - An Array of button names. Indicate a default button by surrounding the text with square brackets like so: "[Cancel]"
+ * @param {MessageIcon|string} [icon=null] - One of MessageIcon icons, or an absolute path to an image from a file system.
+ * @param {Window} [window=null] - Owner window that will be overlaid by this dialog window. If omitted, last created visible Window that's not PopUp will be used.
+ * @return {number|undefined} Returns a zero-based number of a clicked button, or `null` if the dialog window was closed without clicking provided buttons.
+ * @global
+ * @example <h2>Usage example</h2>
+ * let response = dialog("Are you ready?", "Confirm readiness", ["Yes", "No", "[Maybe]"], MessageIcon.Question, window);
+ * switch(response)
+ * {
+ *     case 0: return "Yes";
+ *     case 1: return "No";
+ *     case 2: return "Maybe";
+ * }
+ *
+ * @example <h2>Using custom image</h2>
+ * let response = dialog("Is this you?", "Question #5", ["Yes","[No]"], "C://User/John/profile_icon.jpg", window);
+ */
+export function dialog(message, title = "", buttons = ["OK", "Cancel"], icon = null, window = null)
+{
+	// find first visible window
+	if(window == null)
+	{
+		window = UIComponent.getVisibleWindow();
+	}
+	else if(window instanceof UIComponent) window = window.window;
+	
+	if(!Array.isArray(buttons)) throw new Error(`Invalid argument "buttons" in dialog() function. String array is expected, but received ${typeof buttons}.`);
+	
+	return ui.sendToGUI({
+			java: "showDialog",
+			title: title,
+			message: String(message),
+			buttons: buttons,
+			icon: icon,
+			frame: window != null ? window.id : null
+		},
+		r => r.value,
+		true
+	);
+}