swing-ui 0.1.25 → 1.0.1

package/typedefs.js

@@ -0,0 +1,973 @@
+/**
+ * Type definitions
+ */
+
+// region Event objects
+
+/**
+ * An error event object received by the {@link UIComponent#onError|onError()} handler callback when error occurs.
+ *
+ * @typedef {Object} ErrorEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} messsage - An error message.
+ *
+ * @see {@link UIComponent#onError|onError()}
+ */
+
+/**
+ * A dispose event object received by the {@link UIComponent#onDispose|onDispose()} handler callback when a component gets disposed.
+ *
+ * @typedef {Object} DisposeEvent
+ * @property {object} target - The component that triggered the event.
+ *
+ * @see {@link UIComponent#onDispose|onDispose()}
+ */
+
+/**
+ * Drop event received by the {@link UIComponent#onDropEvents|onDropEvents()} handler callback.
+ *
+ * @typedef {Object} DropEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {object} [source] - The component being dragged onto this component.
+ *                               Present only for component-to-component dragging, and when `DataType.Components` is allowed for dropping.
+ * @property {object} [overComponent] - Descendent of the target component over which the event occurred. Only present for event types `dragover` and `drop`, if target is a container and the event occurred over one of target'a descendent.
+ * @property {string} type - One of `dragenter`, `dragover`, `dragleave`, `drop`.
+ * @property {string} [action] - One of the values of enum DragDropAction. Present when applicable.
+ * @property {object} [data] - Contains the data being dragged/dropped. NOTE: On macOS data is actually present only when type is `drop`, otherwise data types are present, but data is set to `null`.
+ * @property {number} [x] - X position of the pointer relative to this component. Present when type is `dragstart` or `drop`.
+ * @property {number} [y] - Y position of the pointer relative to this component. Present when type is `dragstart` or `drop`.
+ * @property {number} [screenX] - X position of the pointer relative to the screen. Present when type is `dragstart` or `drop`.
+ * @property {number} [screenY] - Y position of the pointer relative to the screen. Present when type is `dragstart` or `drop`.
+ * @property {number[]} [selected] - Selected indexes of a `List` component whose items are being dragged. Present only when dragging List items.
+ *
+ * @see {@link UIComponent#onDropEvents|onDropEvents()}
+ */
+
+/**
+ * Drag event received by the {@link UIComponent#onDragEvents|onDragEvents()} handler callback.
+ *
+ * @typedef {Object} DragEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of `dragstart`, `dragend`, `drag`, `cancel`.
+ * @property {string} [action] - One of the values of enum DragDropAction. Present when applicable.
+ * @property {number} [x] - X position of the pointer relative to this component. Present when type is `dragstart` or `dragend`.
+ * @property {number} [y] - Y position of the pointer relative to this component. Present when type is `dragstart` or `dragend`.
+ * @property {number} [screenX] - X position of the pointer relative to the screen. Present when type is `dragstart` or `dragend`.
+ * @property {number} [screenY] - Y position of the pointer relative to the screen. Present when type is `dragstart` or `dragend`.
+ * @property {number} [button] - Indicates a pointing device button involved in dragging. Value of `MouseButton` enum.
+ * @property {number} [modifiers] - Keyboard modifiers (bitmask or flags). Present when type is `dragstart`.
+ * @property {string} [modifiersText] - Human-readable keyboard modifiers. Present when type is `dragstart`.
+ * @property {boolean} [alt] - Indicates if ALT key was pressed. Present when type is `dragstart`.
+ * @property {boolean} [shift] - Indicates if SHIFT key was pressed. Present when type is `dragstart`.
+ * @property {boolean} [ctrl] - Indicates if CTRL key was pressed. Present when type is `dragstart`.
+ * @property {number[]} [selected] - Selected indexes of a `List` component whose items are being dragged. Present only when dragging List items.
+ *
+ * @see {@link UIComponent#onDragEvents|onDragEvents()}
+ */
+
+/**
+ * Change event received by the {@link UIComponent#onChange|onChange()} handler callback.
+ *
+ * @typedef {Object} ChangeEvent
+ * @property {object}  target - The component that triggered the event.
+ * @property {string}  type - One of `change`, `changing`.
+ *                           `change` - when value has changed and is no longer being modified by the user.
+ *                           `changing` - when the value is still being modified, e.g. while moving a Slider knob.
+ * @property {boolean} [interactive] - Indicates if the change was made by user interacting with the component. `false` means the change was done programmatically.
+ * @property {string}  [action] - One of `inserted`, `removed`. Present for some text editing components, indicates the action performed.
+ * @property {number}  [position] - The position at which text was inserted. Present when `action` is present.
+ * @property {number}  [length] - The number of characters inserted or removed. Present when `action` is present. Applies to text editing components only.
+ * @property {string|number}  [value] - Value of a currently selected {@link RadioButton}, {@link RadioButtonMenuItem} or {@link ToggleButton} within a group.
+ * @property {number}  [index] - Index of a currently selected {@link RadioButton}, {@link RadioButtonMenuItem} or {@link ToggleButton} within a group.
+ * @property {boolean}  [selected] - Indicates if the target {@link RadioButton}, {@link RadioButtonMenuItem} or {@link ToggleButton} component's new state is selected.
+ *
+ * @see {@link UIComponent#onChange|onChange()}
+ * @see RadioButton
+ * @see RadioButtonMenuItem
+ * @see ToggleButton
+ */
+
+/**
+ * Ancestor event received by the {@link UIComponent#onAncestorEvents|onAncestorEvents()} handler callback.
+ *
+ * @typedef {Object} AncestorEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of `add`, `remove`, `move`.
+ * @property {object} ancestor - The ancestor component related to this event.
+ *
+ * @see {@link UIComponent#onAncestorEvents|onAncestorEvents()}
+ */
+
+/**
+ * Scroll event received by the {@link UIComponent#onScroll|onScroll()} handler callback.
+ *
+ * @typedef {Object} ScrollEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of `horizontal`, `vertical`.
+ * @property {number} x - The new horizontal scroll position.
+ * @property {number} y - The new vertical scroll position.
+ * @property {number} maxX - The maximum horizontal scroll position.
+ * @property {number} maxY - The maximum vertical scroll position.
+ *
+ * @see {@link UIComponent#onScroll|onScroll()}
+ */
+
+/**
+ * Caret event received by the {@link UIComponent#onCaretEvents|onCaretEvents()} handler callback.
+ *
+ * @typedef {Object} CaretEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - Always `change`.
+ * @property {number} position - The new caret position.
+ * @property {number} selectionStart - Start position of selected text.
+ * @property {number} selectionEnd - End position of selected text.
+ * @property {number} [line] - Line number where the caret is located. Present in components like `DocumentEditor`.
+ * @property {number} [column] - Column number (offset from line start) of the caret. Present in multi-line components like `DocumentEditor`.
+ * @property {object} [styles] - Text formatting information at the caret’s position. Present only for `DocumentEditor` when HTML is enabled.
+ * @property {string[]} [path] - HTML tag hierarchy at the caret’s position. Present only for `DocumentEditor` when HTML is enabled.
+ *
+ * @see {@link UIComponent#onCaretEvents|onCaretEvents()}
+ */
+
+/**
+ * Action event received by the {@link UIComponent#onAction|onAction()} handler callback.
+ *
+ * @typedef {Object} ActionEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} command - The command string, usually the button text or a custom value set with `.command("")`.
+ * @property {number} [modifiers] - Keyboard modifiers (bitmask or flags).
+ * @property {boolean} [alt] - Indicates if ALT key was pressed.
+ * @property {boolean} [shift] - Indicates if SHIFT key was pressed.
+ * @property {boolean} [ctrl] - Indicates if CTRL key was pressed.
+ * @property {string} type - One of `action` or `index_change`. Present when applicable.
+ * @property {number} [x] - Mouse X position relative to the component.
+ * @property {number} [y] - Mouse Y position relative to the component.
+ * @property {number} [screenX] - Mouse X position relative to the screen.
+ * @property {number} [screenY] - Mouse Y position relative to the screen.
+ * @property {boolean} [interactive] - Indicates if the action was triggered by user interaction (not programmatically).
+ * @property {boolean} [selected] - Indicates selection state when applicable.
+ *
+ * @see {@link UIComponent#onAction|onAction()}
+ */
+
+/**
+ * Mouse event received by the {@link UIComponent#onMouseEvents|onMouseEvents()} handler callback.
+ *
+ * @typedef {Object} MouseEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of `click`, `down`, `up`, `enter`, `leave`.
+ * @property {number} [button] - Button number. One of {@link MouseButton} enum values. Present when type is `click`, `down`, or `up`.
+ * @property {number} [clicks] - Number of times the button was clicked. Present only when applicable, such as when type is `click`.
+ * @property {number} [modifiers] - Keyboard modifiers (bitmask or flags).
+ * @property {boolean} [alt] - Indicates if ALT key was pressed.
+ * @property {boolean} [shift] - Indicates if SHIFT key was pressed.
+ * @property {boolean} [ctrl] - Indicates if CTRL key was pressed.
+ * @property {number} [x] - Mouse X position relative to the component. Present when applicable.
+ * @property {number} [y] - Mouse Y position relative to the component. Present when applicable.
+ * @property {number} [screenX] - Mouse X position relative to the primary screen. Present when applicable.
+ * @property {number} [screenY] - Mouse Y position relative to the primary screen. Present when applicable.
+ *
+ * @see {@link UIComponent#onMouseEvents|onMouseEvents()}
+ *
+ * @example <h2>Detecting a single mouse button left click</h2>
+ * const label = new Label("Click Me").addTo(panel).onMouseEvents(e=>{
+ *     if(e.type === "click" && e.button === MouseButton.Left && e.clicks === 1)
+ *     {
+ *     		console.log("User clicked this label: " + e.target.text());
+ *     }
+ * });
+ */
+
+/**
+ * Mouse motion event received by the {@link UIComponent#onMouseMotion|onMouseMotion()} handler callback.
+ *
+ * @typedef {Object} MouseMotionEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of `move`, `drag`.
+ * @property {number} [button] - Button number. One of `MouseButton` enum values. Present when applicable.
+ * @property {number} [modifiers] - Keyboard modifiers (bitmask or flags).
+ * @property {number} x - Mouse X position relative to the component.
+ * @property {number} y - Mouse Y position relative to the component.
+ * @property {number} screenX - Mouse X position relative to the screen.
+ * @property {number} screenY - Mouse Y position relative to the screen.
+ *
+ * @see {@link UIComponent#onMouseMotion|onMouseMotion()}
+ */
+
+/**
+ * Mouse wheel event received by the {@link UIComponent#onMouseWheel|onMouseWheel()} or {@link SwingUI#onMouseWheel|ui.onMouseWheel()} handler callback.
+ *
+ * @typedef {Object} MouseWheelEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of: `pixels`, `line`, or `pages`.
+ * @property {number} deltaX - Amount of units scrolled in horizontal direction.
+ * @property {number} deltaY - Amount of units scrolled in vertical direction.
+ * @property {number} scrollAmount - Tells how many `pixels`, `line`, or `pages` to scroll, depending on teh `type`.
+ * @property {number} rotation - Number of wheel "clicks" rotated. Can be zero until a full click is accumulated on high-resolution wheels.
+ * @property {number} screenX - Mouse X position relative to the screen.
+ * @property {number} screenY - Mouse Y position relative to the screen.
+ * @property {number} [x] - Mouse X position relative to the component. (not present for global event)
+ * @property {number} [y] - Mouse Y position relative to the component. (not present for global event)
+ * @property {number} [button] - Button number. One of `MouseButton` enum values. Present when applicable.
+ * @property {number} [modifiers] - Keyboard modifiers (bitmask or flags).
+ * @property {boolean} [alt] - Indicates if ALT key was pressed.
+ * @property {boolean} [shift] - Indicates if SHIFT key was pressed.
+ * @property {boolean} [ctrl] - Indicates if CTRL key was pressed.
+ *
+ * @see {@link UIComponent#onMouseWheel|onMouseWheel()}
+ * @see {@link SwingUI#onMouseWheel|ui.onMouseWheel()}
+ */
+
+/**
+ * Key event received by the {@link UIComponent#onKey|onKey()} handler callback.
+ *
+ * @typedef {Object} KeyEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of `up`, `down`, `type`.
+ * @property {number} keyCode - Numeric code associated with the key.
+ * @property {number} [extendedKeyCode] - Unique id assigned to a key depending on the current keyboard layout. Not present for global ui.onKey() events.
+ * @property {string} [keyChar] - The character produced by the key. Present only for `type` events.
+ * @property {number} [modifiers] - Keyboard modifiers (bitmask or flags).
+ * @property {string} [modifiersText] - Human-readable representation of modifiers.
+ * @property {boolean} [alt] - Indicates if ALT key was pressed.
+ * @property {boolean} [shift] - Indicates if SHIFT key was pressed.
+ * @property {boolean} [ctrl] - Indicates if CTRL key was pressed.
+ * @property {boolean} [meta] - Indicates if META (Windows or Command) key was pressed.
+ * @property {string} [keyLocation] - One of `standard`, `numpad`, `left`, `right`. Present for `up` and `down` events.
+ *
+ * @see {@link UIComponent#onKey|onKey()}
+ */
+
+/**
+ * Focus event received by the {@link UIComponent#onFocusEvents|onFocusEvents()} handler callback.
+ *
+ * @typedef {Object} FocusEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of `focus`, `blur`.
+ * @property {string} cause - One of `Unknown`, `Activation`, `TraversalForward`, `TraversalBackward`.
+ * @property {boolean} temporary - Indicates if the focus change is temporary (lost and is expected to return, or gained after being lost tempararily).
+ * @property {boolean} interactive - Indicates if the focus was changed by user interaction. If `false`, then it was changed programmatically.
+ *
+ * @see {@link UIComponent#onFocusEvents|onFocusEvents()}
+ */
+
+/**
+ * Component event received by the {@link UIComponent#onComponentEvents|onComponentEvents()} handler callback.
+ *
+ * @typedef {Object} ComponentEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of `resize`, `move`, `show`, `hide`.
+ * @property {boolean} [interactive] - Indicates if the event was triggered by user interaction (not programmatically). Present for `move` and `resize` for component like Window, InternalWindow.
+ * @property {number} [x] - New X position of the component.
+ * @property {number} [y] - New Y position of the component.
+ * @property {number} [width] - New width of the component. Present when type is `resize`.
+ * @property {number} [height] - New height of the component. Present when type is `resize`.
+ * @property {number} [innerWidth] - New width of the content area. Present for `resize` when component is `Window` or `InternalWindow`.
+ * @property {number} [innerHeight] - New height of the content area. Present for `resize` when component is `Window` or `InternalWindow`.
+ *
+ * @see {@link UIComponent#onComponentEvents|onComponentEvents()}
+ */
+
+/**
+ * Container event received by the {@link UIComponent#onContainerEvents|onContainerEvents()} handler callback.
+ *
+ * @typedef {Object} ContainerEvent
+ * @property {object} target - The container component that triggered the event.
+ * @property {string} type - One of `add`, `remove`.
+ * @property {object} child - The child component that was added or removed.
+ *
+ * @see {@link UIComponent#onContainerEvents|onContainerEvents()}
+ */
+
+/**
+ * Property change event received by the {@link UIComponent#onPropertyChange|onPropertyChange()} handler callback.
+ *
+ * @typedef {Object} PropertyChangeEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - Always `change`.
+ * @property {string} property - The property that was changed.
+ * @property {any} oldValue - Previous value of the changed property.
+ * @property {any} newValue - New value of the changed property.
+ *
+ * @see {@link UIComponent#onPropertyChange|onPropertyChange()}
+ */
+
+/**
+ * Popup list event received by the onPopupEvents() handler callback in ComboBox, Menu and ContextMenu components.
+ *
+ * @typedef {Object} PopupEvent
+ * @property {object} target - The component that triggered the event.
+ * @property {string} type - One of `show`, `hide`, `cancel`.
+ * @property {number} [x] - Component's X position relative to invoker. For `Menu` component it's only present when invoker is not `null`.
+ * @property {number} [y] - Component's Y position relative to invoker. For `Menu` component it's only present when invoker is not `null`.
+ * @property {boolean} interactive - Indicates if the popup was triggered by user's interaction (not programmatically).
+ * @property {number} [screenX] - X position of a `Menu` component relative to default screen.
+ * @property {number} [screenY] - Y position of a `Menu` component relative to default screen.
+ * @property {object} [invoker] - UI Component that invoked the popup, or `null` if it was invoked programmatically.
+ *
+ * @see {@link ComboBox#onPopupEvents|ComboBox.onPopupEvents()}
+ * @see {@link Menu#onPopupEvents|Menu.onPopupEvents()}
+ * @see {@link ContextMenu#onPopupEvents|ContextMenu.onPopupEvents()}
+ */
+
+/**
+ * Event object passed to hyperlink event handlers in {@link DocumentEditor#onLinkEvents}.
+ *
+ * @typedef {Object} LinkEvent
+ * @property {DocumentEditor} target - The component that triggered the event.
+ * @property {string} type - The event type: `click`, `mouseenter`, or `mouseleave`.
+ * @property {string} url - The `href` attribute of the `<a>` tag.
+ * @property {string} text - The text content of the hyperlink.
+ * @property {boolean} shift - Whether the Shift key was pressed.
+ * @property {boolean} ctrl - Whether the Ctrl key was pressed.
+ * @property {boolean} alt - Whether the Alt key was pressed.
+ * @property {string} modifiers - Keyboard modifiers mask.
+ * @property {string} modifiersText - String representation of the keyboard modifiers.
+ *
+ * @see DocumentEditor#onLinkEvents
+ */
+
+/**
+ * Event object passed to MediaPlayer event handlers.
+ *
+ * @typedef {Object} PlayerEvent
+ * @property {string} type - Type of the event: `loadstart`, `loadedmetadata`, `seeking`, `timeupdate`, `play`, `stop`, `subtitle`.
+ * @property {string} [mediaType] - Type of media loaded in the player: `File`, `InputDevice`, `URL`.
+ * @property {Media} [media] - A {@link Media} object containing details about the loaded media.
+ * @property {number} [currentTime] - Current playback time in seconds.
+ * @property {number} [duration] - Total duration of the media in seconds. Present when `type` is `timeupdate`.
+ * @property {string} [reason] - Reason for stopping playback: `Pause`, `EndOfMediaFile`.
+ * @property {number} [index] - Index of a subtitle since the player started playing (not from the beginning of the video}. (Only present when event type is `subtitle`).
+ * @property {string} [fromTime] - Time when to show the subtitle relative to the position when the video started (not to the beginning of the video). (Only present when event type is `subtitle`).
+ * @property {string} [toTime] - Time when to show the subtitle relative to the position when the video started (not to the beginning of the video). (Only present when event type is `subtitle`).
+ * @property {string} [text] - Subtitle text. (Only present when event type is `subtitle`).
+ *
+ * @see MediaPlayer#onPlayerEvents
+ * @see Media
+ * @see VideoStream
+ * @see AudioStream
+ * @see SubtitleStream
+ */
+
+/**
+ * Represents an event related to a Window and InternalWindow component. Used for handling window state changes
+ * such as activation, minimization, maximization, hiding, showing, and closing.
+ *
+ * @typedef {Object} WindowEvent
+ * @property {Window|InternalWindow} target - The window component that triggered the event.
+ * @property {string} type - The event type. One of: `activate`, `deactivate`, `minimize`, `restore`, `closing`, `close`, `show`.
+ * @property {boolean} interactive - Indicates if the event was triggered by the user's interaction with the window.
+ *
+ * @see Window#onWindowEvents
+ * @see InternalWindow#onWindowEvents
+ *
+ * @example <h2>Example of a WindowEvent object:</h2>
+ * const e = {
+ *   target: myWindow,
+ *   type: "activate",
+ *   interactive: true
+ * };
+ */
+
+/**
+ * Represents a window state change event. Used when a window changes its state
+ * such as minimized, maximized, or restored.
+ *
+ * @typedef {Object} WindowStateEvent
+ * @property {Window} target - The window component that triggered the event.
+ * @property {string} type - The event type. Always `change` for state changes.
+ * @property {Window.State} state - The new state of the window.
+ * @property {Window.State} new_state - The previous state of the window.
+ * @property {boolean} interactive - Indicates if the state change was triggered by the user's interaction with the window.
+ *
+ * @see Window#onStateChange
+ * @see InternalWindow#onStateChange
+ *
+ * @example <h2>Example of a WindowStateEvent object:</h2>
+ * const e = {
+ *   target: myWindow,
+ *   type: "change",
+ *   oldValue: Window.State.Minimized,
+ *   newValue: Window.State.Normal,
+ *   interactive: true
+ * };
+ */
+
+/**
+ * Represents an application event used in `{@link SwingUI#onAppEvents|ui.onAppEvents(callback)}`.
+ *
+ * @typedef {Object} AppEvent
+ * @property {string} type - One of event types: `about`, `foreground`, `background`, `searchTerm`, `files`, `print`, `uri`, `preferences`, `quit`, `screenSleep`, `screenAwake`, `systemSleep`, `systemAwake`
+ * @property {string[]} [files] - File list. Present when type is `files` or `print`.
+ * @property {string} [searchTerm] - Present when type is `files`.
+ *
+ * @see SwingUI#onAppEvents
+ *
+ * @example <h2>Example of a `print` AppEvent object:</h2>
+ * const e = {
+ *   type: "print",
+ *   files: [
+ *       "/home/mike/Desktop/Document.pdf"
+ *   ]
+ * };
+ */
+
+/**
+ * Represents a table row event triggered by a `{@link Table}` component `{@link Table#onRowEvents}` events.
+ *
+ * @typedef {Object} RowEvent
+ * @property {Table} target - The Table component that triggered the event.
+ * @property {string} type - Type of the row event: `insert`, `remove`, `update`.
+ * @property {number} [row] - Index of the affected row. Present when a single row is affected.
+ * @property {number} [column] - Column index of the affected cell. Only present when type is `update`.
+ * A value of `-1` means all columns in the row were affected.
+ * @property {number} [fromRow] - Start index of affected row range. Present when multiple rows are affected.
+ * @property {number} [toRow] - End index of affected row range. Present when multiple rows are affected.
+ * @property {boolean} [interactive] - Only present when type is `update`.
+ * `true` if the update was triggered by user interaction, `false` if done programmatically.
+ *
+ * @see Table#onRowEvents
+ *
+ * @example <h2>Single row insert event:</h2>
+ * const e = {
+ *   target: table,
+ *   type: "insert",
+ *   row: 3
+ * };
+ *
+ * @example <h2>Cell update by user:</h2>
+ * const e = {
+ *   target: table,
+ *   type: "update",
+ *   row: 2,
+ *   column: 1,
+ *   interactive: true
+ * };
+ *
+ * @example <h2>Range removal:</h2>
+ * const e = {
+ *   target: table,
+ *   type: "remove",
+ *   fromRow: 5,
+ *   toRow: 10
+ * };
+ */
+
+/**
+ * Represents a table column event triggered by a `{@link Table}` component.
+ *
+ * @typedef {Object} ColumnEvent
+ * @property {Table} target - The Table component that triggered the event.
+ * @property {string} type - Type of the column event: `insert`, `remove`, `move`, `resize`;
+ * @property {number} [index] - Column index. Present when type is `insert`, `remove`, or `resize`.
+ * @property {number} [fromIndex] - Previous column index. Present when type is `move`.
+ * @property {number} [toIndex] - New column index. Present when type is `move`.
+ * @property {number} [fromSize] - Previous column size. Present when type is `resize`.
+ * @property {number} [toSize] - New column size. Present when type is `resize`.
+ * @property {boolean} [interactive] - Present for `move` events. `true` if triggered by user interaction, `false` if done programmatically.
+ *
+ * @see Table#onColumnEvents
+ * @see Table
+ *
+ * @example <h2>Insert column:</h2>
+ * const e = {
+ *   target: table,
+ *   type: "insert",
+ *   index: 2
+ * };
+ *
+ * @example <h2>Move column:</h2>
+ * const e = {
+ *   target: table,
+ *   type: "move",
+ *   fromIndex: 1,
+ *   toIndex: 4,
+ *   interactive: true //
+ * };
+ *
+ * @example <h2>Resize column:</h2>
+ * const e = {
+ *   target: table,
+ *   type: "resize",
+ *   index: 3,
+ *   fromSize: 120,
+ *   toSize: 200
+ * };
+ */
+
+/**
+ * Represents a table sort event triggered by a `{@link Table}` component.
+ *
+ * @typedef {Object} SortEvent
+ * @property {Table} target - The Table component that triggered the event.
+ * @property {Table.SortOrder} type - Sort order state: `Table.SortOrder.None`, `Table.SortOrder.Ascending`, or `Table.SortOrder.Descending`.
+ * @property {number} [column] - Column index. Present when type is not `Table.SortOrder.None`.
+ * @property {number} [newOrderColumn] - New column index after reordering. Present when type is not `Table.SortOrder.None`.
+ * @property {boolean} interactive - `true` if triggered by user interaction, `false` if triggered programmatically.
+ *
+ * @see Table#onSort
+ * @see Table
+ *
+ * @example <h2>Clear sorting:</h2>
+ * const e = {
+ *   target: table,
+ *   type: Table.SortOrder.None,
+ *   interactive: true
+ * };
+ *
+ * @example <h2>Ascending sort:</h2>
+ * const e = {
+ *   target: table,
+ *   type: Table.SortOrder.Ascending,
+ *   column: 2,
+ *   newOrderColumn: 0,
+ *   interactive: true
+ * };
+ *
+ * @example <h2>Descending sort:</h2>
+ * const e = {
+ *   target: table,
+ *   type: Table.SortOrder.Descending,
+ *   column: 1,
+ *   newOrderColumn: 3,
+ *   interactive: false
+ * };
+ */
+
+/**
+ * Represents an event triggered by a performing a keyboard shortcut (one key or a key combination) on a component.
+ *
+ * @typedef {Object} ShortcutEvent
+ * @property {UIComponent} target - The component that triggered the event.
+ * @property {ShortcutScope} scope - One of values from {@link ShortcutScope} enum.
+ * @property {string} action - User provided action string, or the key exactly as user specifed it (not normalized).
+ * @property {string} key - The keyboard key or a key combination that triggered the shortcut (normalized, might be not exactly same as user specified).
+ *
+ * @see UIComponent#onShortcut
+ * @see UIComponent#shortcuts
+ * @see ShortcutScope
+ */
+
+/**
+ * Shape event received by the {@link Panel#onShapeEvents|onShapeEvents()} and {@link Window#onShapeEvents|Window.onShapeEvents()} handler callback.
+ *
+ * @typedef {Object} ShapeEvent
+ * @property {object} target - The Panel component that triggered the event.
+ * @property {string} type - One of: `add`, `remove`, `click`, `mousedown`, `mouseup`, `mouseenter`, `mouseleave`, `mousemove`.
+ * @property {number} [x] - X position of the pointer relative to the target component.
+ * @property {number} [y] - Y position of the pointer relative to the target component.
+ * @property {number} shapeIndex - Index of the shape that triggered the event.
+ * @property {boolean} [dragging] - `true` if mouse is down while moving, otherwise `false`.
+ * @property {boolean} [alt] - `true` if Alt key was pressed on keyboard when event was emitted.
+ * @property {boolean} [shift] - `true` if Shift key was pressed on keyboard when event was emitted.
+ * @property {boolean} [ctrl] - `true` if Control key was pressed on keyboard when event was emitted.
+ * @property {string} [modifiers] - Modifiers used when the event was emitted.
+ * @property {string} [modifiersText] - Description of used modifiers.
+ *
+ * @see {@link Panel#onShapeEvents|Panel.onShapeEvents()}
+ * @see {@link Window#onShapeEvents|Window.onShapeEvents()}
+ * @see Shape#active
+ */
+
+//endregion
+
+//region Other
+
+/**
+ * List item object used in {@link ComboBox}, {@link List}, and {@link Tree} components.
+ *
+ * @typedef {Object} ListItem
+ * @property {string} [text] - Item text. (Required for a new list item).
+ * @property {string|number} [id] - Value that can be used by software logic to identify this item.
+ * @property {string|number} [value] - Additional value to be stored in the item for later use.
+ * @property {string|null} [icon] - Absolute/relative path to icon image, base64 encoded image string, or `null` to remove icon.
+ * @property {string} [color] - Item text color as a hex string (e.g. `#665500`).
+ * @property {string} [background] - Item background color as a hex string (e.g. `#665500`).
+ * @property {string} [tooltip] - Tooltip text shown when hovering the item (only in List and Tree components).
+ * @property {Font} [font] - {@link Font} formatted object.
+ * @property {boolean} [editable] - Specifies if the Tree node Item text can be edited by the user. (only in Tree components)
+ * @property {number} [index] - In some cases items are returned with `index` property to indicate their position within component.
+ * @property {ListItem[]} [children] - For Tree component nodes only! An array of child nodes.
+ *
+ * @see List
+ * @see ComboBox
+ * @see Tree
+ * @see Font
+ */
+
+/**
+ * Font object used in most UI components, {@link ListItem}, {@link TableColumn}, {@link Text} shape and other text-rendering components.
+ *
+ * @typedef {Object} Font
+ * @property {string|FontFamily} [name] - Font family name (e.g., `"sans-serif"`).
+ * @property {number} [size] - Font size in pixels.
+ * @property {boolean} [bold] - Whether the text is bold.
+ * @property {boolean} [italic] - Whether the text is italic.
+ * @property {boolean} [underlined] - Whether the text is underlined.
+ * @property {boolean} [strikethrough] - Whether the text has a strikethrough.
+ * @property {string} [direction] - Text direction: `"ltr"` or `"rtl"`.
+ * @property {boolean} [kerning] - Enable or disable kerning.
+ * @property {boolean} [ligatures] - Enable or disable font ligatures.
+ * @property {number} [tracking] - Letter spacing adjustment: -1, 0 (default), or 1.
+ *
+ * @see FontFamily
+ * @see UIComponent#font
+ * @see ListItem
+ * @see TableColumn
+ * @see Text
+ */
+
+/**
+ * Border object used to define the visual border of UI components like Panel, Label, Button, TextField, TextArea and more.
+ *
+ * @typedef {Object} Border
+ * @property {BorderStyle} style - (Required) The border style.
+ * @property {number} [width] - Border width in pixels. Must be >= 1.
+ * @property {string} [padding] - Inner padding as a space-separated string of four integer values: `"top right bottom left"`. Example: `"5 10 5 10"`. Can be set even when `style` is `"none"`.
+ * @property {string} [color] - Border color. Only applicable for `"line"` or `"dashed"` styles.
+ * @property {boolean} [rounded] - If `true`, renders rounded corners for `"line"` style, or rounded dashes for `"dashed"` style. Only applicable for `"line"` or `"dashed"` styles.
+ * @property {number} [length] - Length of each dash. Only applicable for `"dashed"` style.
+ * @property {number} [spacing] - Length of the gaps between dashes. Only applicable for `"dashed"` style.
+ * @property {number} [offset] - Starting offset of the dash pattern. Can be used to animate dashes. Only applicable for `"dashed"` style.
+ * @property {string} [text] - Label text displayed at the top-left of the border, creating a titled border effect.
+ * @property {string} [alignment] - Placement of the border label text. Accepts a combination of: `"left"`, `"center"`, `"right"`, `"leading"`, `"trailing"`, `"top"`, `"bottom"`, `"above"`, `"below"`. `"above"` and `"below"` refer to placement relative to the border line itself. Defaults to `"top left"`.
+ * @property {Font} [font] - Font used to render the border label text.
+ *
+ * @see UIComponent#border
+ * @see BorderStyle
+ * @see Font
+ */
+
+/**
+ * Table column configuration object used in {@link Table} components.
+ *
+ * @typedef {Object} TableColumn
+ * @property {string} [text] - The text to be displayed in the column header. (Required when creating a new column)
+ * @property {string} [type="text"] - Type of component to display/edit cell data. Possible values:
+ *   - `text` - Plain text or HTML.
+ *   - `password` - Masked password text field.
+ *   - `textarea` - Multi-line text field.
+ *   - `icon` - Displays an image loaded from the cell's value as a URL or path. Use table.onAction(callback) for click events.
+ *   - `button` - A string of button names separated by `"|"`. Use table.onAction(callback) for click events.
+ *   - `checkbox` - Boolean check mark selection component.
+ *   - `combobox` - Drop-down list of values, can be editable.
+ *   - `progress` - Progress bar showing integer value 0–100.
+ * @property {number} [width] - Initial desired width of the column.
+ * @property {number} [minWidth] - Minimum width column can be resized to.
+ * @property {number} [maxWidth] - Maximum width column can be resized to.
+ * @property {boolean} [editable=false] - Whether text fields are editable.
+ * @property {number} [clicksToEdit] - Number of clicks required to enter edit mode. Takes effect only when `editable` is `true`.
+ * @property {boolean} [resizable=true] - Indicates if the column can be resized by the user.
+ * @property {boolean} [autoResize=false] - Indicates if column auto-resizes with table (Has no effect if the table's auto-resize mode is Table.AutoResize.None).
+ * @property {boolean} [hidden=false] - Whether the column is hidden by collapsing its width to 0.
+ * @property {boolean} [primary=false] - Indicates a column with primary data, such as a URL or file path, used as the data source for list generation or drag-and-drop operations.
+ * @property {Table.Sorting} [sorting=Table.Sorting.Natural] - Sorting mode. `Table.Sorting.None` disables sorting.
+ * @property {string[]} [options] - List of values to choose from in a ComboBox component when type is `combobox`.
+ * @property {string} [echoChar] - The character used to mask input for the `password` type.
+ * @property {string} [icon] - Icon shown in the column header. Value can be a local file path, URI, or base64 encoded image string.
+ * @property {number} [iconSize] - For `"icon"` type, fixed width/height of the icon (largest dimension).
+ * @property {number} [cacheCapacity=10] - For `"icon"` type, number of images cached in RAM.
+ * @property {string} [tooltip] - Tooltip for the column header.
+ * @property {string|null} [color] - Text color of cells of the column.
+ * @property {string|null} [background] - Background color of cells of the column.
+ * @property {string|null} [headerColor] - Text color of a column header.
+ * @property {string|null} [headerBackground] - Background color of a column header.
+ * @property {Font|null} [font] - Font of cells of a column.
+ * @property {Font|null} [headerFont] - Font of a column header.
+ * @property {number} [min] - Minimum value for progress bar component when type is `progress`.
+ * @property {number} [max] - Maximum value for progress bar component when type is `progress`.
+ * @property {boolean} [showText] - Whether to display the value as text inside the progress bar component when type is `progress`.
+ * @property {string} [align] - Text alignment in cells of the column. Maximum one horizontal and one vertical alignment keywords: 'center','left','right','leading','trailing','top','bottom'.
+ * @property {string} [headerAlign] - Text alignment of a column header. Maximum one horizontal and one vertical alignment keywords: 'center','left','right','leading','trailing','top','bottom'.
+ *
+ * @see Table
+ * @see Table#columns
+ * @see Table#addColumn
+ * @see Font
+ *
+ * @example <h2>Creating a simple column object:</h2>
+ * let column = {
+ *     text: "New Column",
+ *     headerAlign: "center"
+ * };
+ */
+
+/**
+ * Table cell coordinates containing column and row property.
+ *
+ * @typedef {Object} Cell
+ * @property {number} column - a column index of the cell
+ * @property {number} row - a row index of the cell
+ *
+ * @see Table#cellAt
+ * @see Table#findCell
+ * @see Table#findCells
+ *
+ */
+
+/**
+ * Describes metadata and streams of the media.
+ *
+ * @typedef {Object} Media
+ * @property {number} [duration] - Duration of the media in seconds. Not present for live streams.
+ * @property {VideoStream[]} videoStreams - Array of video streams available in the media.
+ * @property {AudioStream[]} audioStreams - Array of audio streams available in the media.
+ * @property {SubtitleStream[]} subtitleStreams - Array of subtitle streams available in the media.
+ *
+ * @see MediaPlayer#onPlayerEvents
+ * @see VideoStream
+ * @see AudioStream
+ * @see SubtitleStream
+ */
+
+/**
+ * Describes a video stream in the media.
+ *
+ * @typedef {Object} VideoStream
+ * @property {number} sampleWidth - Original width of the video frame in pixels.
+ * @property {number} sampleHeight - Original height of the video frame in pixels.
+ * @property {number} width - Display width of the video.
+ * @property {number} height - Display height of the video.
+ * @property {string} pixelAspectRatio - Pixel aspect ratio (e.g., `"1:1"`).
+ * @property {string} displayAspectRatio - Display aspect ratio (e.g., `"16:9"`).
+ * @property {number} frameRate - Frame rate of the video stream.
+ * @property {string} codec - Codec used to encode the video stream (e.g., `"h264"`).
+ * @property {string} pixelFormat - Pixel format of the video stream (e.g., `"yuv420p"`).
+ * @property {boolean} progressive - Whether the video stream is progressive or interlaced.
+ * @property {boolean} default - Indicates if this is the default video stream.
+ *
+ * @see MediaPlayer#onPlayerEvents
+ * @see Media
+ */
+
+/**
+ * Describes an audio stream in the media.
+ *
+ * @typedef {Object} AudioStream
+ * @property {number} sampleRate - Sample rate of the audio stream in Hz.
+ * @property {number} channels - Number of audio channels (1 - mono, 2 - stereo, etc.)
+ * @property {number} bitDepth - Bit depth of the audio samples.
+ * @property {string} codec - Codec used to encode the audio stream (e.g., `"aac"`).
+ * @property {boolean} default - Indicates if this is the default audio stream.
+ *
+ * @see MediaPlayer#onPlayerEvents
+ * @see Media
+ */
+
+/**
+ * Describes a subtitle stream in the media.
+ *
+ * @typedef {Object} SubtitleStream
+ * @property {string} language - Language of the subtitle stream (e.g., `"en"`).
+ * @property {string} codec - Codec used for the subtitle stream (e.g., `"srt"`).
+ * @property {boolean} default - Indicates if this is the default subtitle stream.
+ *
+ * @see MediaPlayer#onPlayerEvents
+ * @see Media
+ */
+
+/**
+ * Represents a video input device, such as WebCam, video capture device, etc. Used when getting input devices with {@link MediaPlayer#videoInputDevices|videoInputDevices} getter and when setting input device with {@link MediaPlayer#setInputDevice|setInputDevice()} method.
+ *
+ * @typedef {Object} VideoDevice
+ * @property {string} [name] - Name of the video input device (only present when retrieving a list of video input devices).
+ * @property {string} id - ID of the video input device.
+ * @property {VideoFormat[]} [formats] - List of available video formats (only present when retrieving a list of video input devices).
+ * @property {VideoFormat} [format] - Chosen video format to use (required when setting a video input device).
+ *
+ * @see MediaPlayer#videoInputDevices
+ * @see MediaPlayer#setInputDevice
+ * @see VideoFormat
+ *
+ * @example <h2>Setting a video input device:</h2>
+ * const devices = player.videoInputDevices;
+ * console.log(devices[0].formats[0]); // prints first format of a first device
+ * const first_format = devices[0].formats[0];
+ *
+ * // create new VideoDevice formatted object
+ * const video_device = {
+ *     id: devices[0].id,
+ *     format: {
+ *         size: first_format.size,
+ *         fps: first_format.max_fps,
+ *         pixel_format: first_format.pixel_format, // set pixel_format in case when it is used instead of vcodec
+ *         vcodec: first_format.vcodec              // set vcodec in case when it is used instead of pixel format
+ *     }
+ * }
+ *
+ * // set the video device and start playing
+ * player.setInputDevice(video_device).play();
+ */
+
+/**
+ * Represents a video format for a VideoDevice. When using this VideoFormat for video input device, make sure that either "pixel_format" or "vcodec" is specified as it was set when you retrieved the supported formats.
+ *
+ * @typedef {Object} VideoFormat
+ * @property {string} size - Video frame size in pixels (e.g., "1920x1080").
+ * @property {number} [min_fps] - Minimum available frame rate (e.g., 7.5). (provided when retrieving video input devices)
+ * @property {number} [max_fps] - Maximum available frame rate (e.g., 30). (provided when retrieving video input devices)
+ * @property {number} [fps] - Frame rate in frames per second (required when setting a video input device).
+ * @property {string} [pixel_format] - Frame image pixel format coming out of the device (e.g., "yuyv422"). If this is present, then `vcodec` is absent.
+ * @property {string} [vcodec] - Encoded video format that the video device supports (e.g., "mjpeg", "h264"). If this is present, then `pixel_format` is absent.
+ *
+ * @see VideoDevice
+ *
+ * @example <h2>Example of a VideoFormat object when retrieved with input devices:</h2>
+ * const devices = player.videoInputDevices;
+ * const first_format = devices[0].formats[0];
+ * console.log(first_format); // prints first format of a first device
+ *
+ * // outputs something like:
+ * {
+ *     size: "1920x1080",
+ *     min_fps: 5,
+ *     max_fps: 30,
+ *     pixel_format: "yuyv422"
+ * }
+ *
+ * @example <h2>Setting a video input device:</h2>
+ * const devices = player.videoInputDevices;
+ * console.log(devices[0].formats[0]); // prints first format of a first device
+ * const first_format = devices[0].formats[0];
+ *
+ * // create new VideoDevice formatted object
+ * const video_device = {
+ *     id: devices[0].id,
+ *     format: {
+ *         size: first_format.size,
+ *         fps: first_format.max_fps,
+ *         pixel_format: first_format.pixel_format, // set pixel_format in case when it is used instead of vcodec
+ *         vcodec: first_format.vcodec              // set vcodec in case when it is used instead of pixel format
+ *     }
+ * }
+ *
+ * // set the video device and start playing
+ * player.setInputDevice(video_device).play();
+ *
+ */
+
+/**
+ * Represents an audio input or output device, such as a microphone, audio card, etc.
+ *
+ * @typedef {Object} AudioDevice
+ * @property {string} name - Name of the audio device (required when setting an audio input device).
+ * @property {string} [id] - ID of the audio device.
+ * @property {AudioFormat[]} [formats] - List of available audio formats provided when retrieving a list of installed audio devices.
+ * @property {AudioFormat} [format] - Specifies the chosen audio format to use (only when setting audio input device).
+ *
+ * @see MediaPlayer#audioInputDevices
+ * @see MediaPlayer#audioOutputDevice
+ * @see AudioFormat
+ */
+
+/**
+ * Represents an audio format for an audio device.
+ *
+ * @typedef {Object} AudioFormat
+ * @property {number} channels - Number of audio channels. (1-Mono, 2-Stereo, etc.)
+ * @property {number} bits - Bits per audio sample.
+ * @property {number} [rate] - Sample rate in Hz (only available for audio input devices).
+ * @property {string} [encoding] - Audio encoding (e.g., "PCM_UNSIGNED", "PCM_SIGNED"); (only available for audio output device formats).
+ *
+ * @see AudioDevice
+ */
+
+/**
+ * Represents a point in 2D space with X and Y coordinates. Used when setting or getting position of UI component, Shape position, or Shape's anchor.
+ *
+ * @typedef {Object} Point
+ * @property {number} x - The x-coordinate.
+ * @property {number} y - The y-coordinate.
+ *
+ * @see UIComponent#position
+ * @see Shape#position
+ * @see Shape#anchor
+ *
+ * @example <h2>Example of a Point object:</h2>
+ * const point = {x: 300, y: 200};
+ */
+
+/**
+ * Represents the size of a 2D object. Used when setting or getting the size of UI component, Shape size, and more.
+ *
+ * @typedef {Object} Size
+ * @property {number} width - The width dimension.
+ * @property {number} height - The height dimension.
+ *
+ * @see UIComponent#size
+ * @see UIComponent#minSize
+ * @see UIComponent#maxSize
+ * @see Window#innerSize
+ * @see Window#screenSize
+ * @see InternalWindow#innerSize
+ * @see Shape#size
+ * @see Rectangle#size
+ * @see Ellipse#size
+ *
+ * @example <h2>Example of a Size object:</h2>
+ * const size = {width: 300, height: 200};
+ */
+
+/**
+ * Options object for configuring file or directory selection dialogs. Used in {@link Window#chooseFile}.
+ *
+ * @typedef {Object} FileChooserOptions
+ * @property {boolean} directory - `true` to select directories, `false` to select files.
+ * @property {boolean} save - `true` to display a Save dialog, `false` for an Open dialog.
+ * @property {boolean} multiple - `true` to allow selection of multiple files or folders.
+ * @property {boolean} hidden - `true` to display hidden files.
+ * @property {string} filter - File type filter string (e.g. `"Documents:doc,docx,txt,rtf|Music:mp3,m4a,ogg,wma|Images:gif,jpg,jpeg,bmp,webp"`).
+ * @property {string} path - Initial directory path or file path to open in the dialog.
+ *
+ * @see Window#chooseFile
+ */
+
+/**
+ * Options object that hold optional video filters to be applied to video by FFMPEG for MediaPlayer component. Used in {@link MediaPlayer#videoFilters}.
+ *
+ * @typedef {Object} VideoFilters
+ * @property {number} [rotate] - A number of degrees to rotate the video by.
+ * @property {string} [flip] - `h` for horizontal, `v` for vertical.
+ * @property {string} [color] - `gray`, `sepia`, or `negative`.
+ * @property {number} [brightness] - A number between 1 and -1. Default is 0.
+ * @property {number} [contrast] - A number between 0.0 and 2.0. Default is 1.
+ * @property {number} [saturation] - A number between 0.0 and 3.0. Default is 1.
+ * @property {number} [gamma] - A number between 0.1 and 10.0. Default is 1.
+ * @property {string} [custom] - Allows to insert any custom video filters separated by comma. Must be compatible with `ffmpeg -vf` option.
+ *
+ * @see MediaPlayer#videoFilters
+ */
+
+/**
+ * An object returned by ui.fileStat(path), which contains information about a file or directory.
+ *
+ * @typedef {Object} FileStat
+ * @property {boolean} isFile - Indicates if the entry is a regular file
+ * @property {boolean} isDirectory - Indicates if the entry is a directory
+ * @property {boolean} isSymlink - Indicates if the entry is a symbolic link
+ * @property {number} dev - Device ID containing the file
+ * @property {number} rdev - Device ID (if special file)
+ * @property {number} nlink - Number of hard links
+ * @property {number} user - User ID of the file owner
+ * @property {number} group - Group ID of the file owner
+ * @property {number} size - Size of the file in bytes
+ * @property {number} mode - File mode (permissions and file type)
+ * @property {Date} atime - Last access time
+ * @property {Date} mtime - Last modification time (e.g. 2025-11-10T08:13:44.386Z)
+ * @property {Date} ctime - Last status change time (e.g. 2025-11-10T08:13:44.386Z)
+ * @property {Date} birthtime - File creation time (e.g. 2025-11-10T08:13:44.386Z)
+ *
+ * @see SwingUI#fileStat
+ */
+
+/**
+ * An object returned and accepted by .scrollbars() method for components with scroll bars, which contains scroll bar settings for horizontal and vertical scroll bars.
+ *
+ * @typedef {Object} Scrollbars
+ * @property {boolean|null} [horizontal] - Visibility of horizontal scroll bar: `true` = visible, `false` = hidden, `null` = auto.
+ * @property {boolean|null} [vertical] - Visibility of horizontal scroll bar: `true` = visible, `false` = hidden, `null` = auto.
+ *
+ * @see UIComponent#scrollbars
+ */
+
+//endregion