swing-ui 0.1.25 → 1.0.1

package/types/classes/Window.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Window UI component that extends ShapesContainer class which extends UIComponent.
+ * For more methods for this component check ShapesContainer and UIComponent classes.
+ *
+ * @glass
+ * @global
+ * @example <h2>To create a new custom window class (recommended way for main window):</h2>
+ * class MyWindow extends Window
+ * {
+ *      constructor()
+ *      {
+ *          super("My New Application"); //
+ *      }
+ * }
+ *
+ * // appWindow1 will be accessible globally.
+ * globalThis.appWindow1 = new MyWindow();
+ */
+export class Window extends ShapeContainer {
+    /**
+     * Represents the behavior when a close button is clicked or close() method is called.
+     * Applies to {@link Window} and {@link InternalWindow} components.
+     *
+     * @readonly
+     * @enum {number}
+     * @property {number} Nothing - Do nothing; the close button has no effect. WindowEvent with type "closing" still gets emitted to report intent to close.
+     * @property {number} Hide - Hide the window instead of closing it.
+     * @property {number} Dispose - Release window resources and remove it from display. Emits 2 WindowEvent events, with type "closing" and with "close".
+     * @property {number} Exit - Terminate the entire application. Emits 2 WindowEvent events, with type "closing" and with "close".
+     * @see Window
+     * @see InternalWindow
+     * @example
+     * window.closeOperation(Window.CloseOperation.Exit); // setting most common window close operation
+     */
+    static readonly CloseOperation: Readonly<{
+        Nothing: 0;
+        Hide: 1;
+        Dispose: 2;
+        Exit: 3;
+    }>;
+    /**
+     * Represents the display state of a {@link Window}. Pass one of these values to {@link Window#state} to get or set the Window's current state.
+     *
+     * @readonly
+     * @enum {number}
+     * @property {number} Normal - The window is in its default, restored state (not minimized or maximized).
+     * @property {number} Minimized - The window is collapsed to the taskbar or dock.
+     * @property {number} Maximized - The window is expanded to fill the entire application area on the screen.
+     * @property {number} MaximizedHorizontally - The window is maximized horizontally but not vertically. Doesn't apply to {@link InternalWindow} component.
+     * @property {number} MaximizedVertically - The window is maximized vertically but not horizontally. Doesn't apply to {@link InternalWindow} component.
+     * @see Window#state
+     * @see Window#minimize
+     * @see Window#maximize
+     * @see InternalWindow#state
+     * @example <h2>Checking and setting Window state</h2>
+     * if(window.state() === Window.State.Minimized)
+     * {
+     *    window.state(Window.State.Normal);
+     * }
+     */
+    static readonly State: Readonly<{
+        Normal: 0;
+        Minimized: 1;
+        Maximized: 2;
+        MaximizedHorizontally: 3;
+        MaximizedVertically: 4;
+    }>;
+    /**
+     * Represents the type of the window. Used when creating or modifying a window's appearance or behavior.
+     *
+     * @readonly
+     * @enum {number}
+     * @property {number} Normal - A standard, resizable window with borders, title bar and a taskbar button.
+     * @property {number} Borderless - A window with a task bar button, but without border and title bar.
+     * @property {number} Utility - A smaller utility window without a taskbar button, typically used for tools or palettes.
+     * @property {number} Popup - A popup window, usually without a title bar, borders and taskbar button.
+     * @see Window#type
+     * @example
+     * let window = ne Window("New window", parent_window, Window.Type.Utility);
+     */
+    static readonly Type: Readonly<{
+        Normal: 0;
+        Borderless: 1;
+        Utility: 2;
+        Popup: 3;
+    }>;
+    _shapes: any[];
+    temp_token: undefined;
+    /**
+     * Returns Window component that is set as an owner of this Window, or `null` if owner Window was not set.
+     *
+     * @readonly
+     * @type {Window|null}
+     */
+    readonly get owner(): Window | null;
+    /**
+     * Gets the current Window type.
+     *
+     * @readonly
+     * @type {Window.Type}
+     * @see Window#Type
+     */
+    readonly get type(): Readonly<{
+        Normal: 0;
+        Borderless: 1;
+        Utility: 2;
+        Popup: 3;
+    }>;
+    /**
+     * Returns the size of the screen that the Window occupies. If the Window is not on any screen, then returns default screen's size. If the Window was never displayed on a screen, then `null` is returned.
+     *
+     * @readonly
+     * @type {Size}
+     */
+    readonly get screenSize(): Size;
+    /**
+     * Returns an offset of each side of content pane of the Window relative to Window's edges. See example below:
+     *
+     * @readonly
+     * @type {Object}
+     * @example
+     * // Returned object format:
+     * {
+     *     top: number,
+     *     right: number,
+     *     bottom: number,
+     *     left: number
+     * }
+     */
+    readonly get innerOffset(): Object;
+    /**
+     * Sets or gets the operation to perform when a Window close button is clicked by a user or a close() method is called on this Window.
+     *
+     * @param {Window.CloseOperation} [operation] - One of Window.CloseOperation enum values. Default is Window.CloseOperation.Close.
+     * @return {Window|Window.CloseOperation} Returns `this` component if argument is provided, otherwise returns value.
+     */
+    closeOperation(...args: any[]): Window | Readonly<{
+        Nothing: 0;
+        Hide: 1;
+        Dispose: 2;
+        Exit: 3;
+    }>;
+    /**
+     * Gets, registers or unregisters an event handler for when the state of the Window changes between normal, minimized, maximized.
+     *
+     * @param {function(WindowStateEvent): any} [callback] - The event handler function receiving {@link WindowStateEvent} event object.
+     * @param {boolean} [remove=false] - Set to `true` to unregister the event handler.
+     * @returns {this}
+     * @see Window#State
+     * @example
+     * // Example event object:
+     * const e = {
+     *   target: Window,            // The component that triggered the event.
+     *   type: string,              // `change`
+     *   oldValue: Window.State,    // Previous state
+     *   newValue: Window.State,    // New state
+     *   interactive: boolean       // Indicates if the state was changed by user's interaction with window
+     * };
+     */
+    onStateChange(...args: any[]): this;
+    /**
+     * Gets, registers or unregisters an event handler for window events, such as activate, deactivate, closed, etc.
+     *
+     * @param {function(WindowEvent): any} [callback] - The event handler function receiving {@link WindowEvent} event object.
+     * @param {boolean} [remove=false] - Set to `true` to unregister the event handler.
+     * @returns {this}
+     *
+     * @example
+     * // Example event object:
+     * const e = {
+     *   target: Window,            // The component that triggered the event.
+     *   type: string,              // `activate`, `deactivate`, `minimize`, `restore`, `closing`, `close`, `show`
+     *   interactive: boolean       // Indicates if triggered by user's interaction with window
+     * };
+     */
+    onWindowEvents(...args: any[]): this;
+    /**
+     * Performs previously specified close operation on this Window.
+     * To specify what operation should be performed use closeOperation(Window.CloseOperation.[Nothing|Exit|Hide|Dispose])
+     *
+     * @return {Window} Returns this window component
+     */
+    close(): Window;
+    /**
+     * Shows a dialog window asking user to confirm your message. User has an option to press OK or Cancel, which result in returned values `true` or `false` respectively.
+     *
+     * @param {string} message - Message to show in dialog window.
+     * @return {boolean} Returns `boolean` indicating if user confirmed the message or not.
+     */
+    confirm(message: string): boolean;
+    /**
+     * Opens file/directory chooser dialog window. Check example for all possible options.
+     *
+     * @param {FileChooserOptions} options - JSON Object with valid options. See example for full list of options.
+     * @returns {string|string[]|null} Returns `string` path if `multiple` option is `false`, `string[]` if `multiple` option is `true`, or `null` if file chooser was closed without making a selection.
+     * @example
+     * window.chooseFile({
+     *  directory: false,          // `true` for Directory selection, `false` for Files.
+     *  save: true,               // `true` for `Save` dialog box, `false` for `Open`.
+     *  multiple: false,           // [true|false] to be able to select multiple files/folders.
+     *  hidden:false,              // [true|false] to show hidden files.
+     *  filter:"Documents:doc,docx,txt,rtf|Music:mp3,m4a,ogg,wma|Images:gif,jpg,jpeg,bmp,webp", // File extension can have multiple "." characters, such as "file.d.ts".
+     *  path:"Initial-Path/file.ext" // Default path to open in the dialog window.
+     * });
+     * @see FileChooserOptions
+     */
+    chooseFile(options: FileChooserOptions): string | string[] | null;
+    /**
+     * Opens color chooser dialog window.
+     *
+     * @param {string} [title] - Dialog window title text
+     * @param {string} [initial_color] - Default color to show in dialog window before a new one is chosen.
+     * @returns {string|null} Returns a string of a chosen color.
+     */
+    chooseColor(title?: string, initial_color?: string): string | null;
+    /**
+     * Opens font chooser dialog window.
+     *
+     * @param {string} [title] - Dialog window title text
+     * @param {Object} [initial_font] - Pre-fills dialog window with specified font properties.
+     * @returns {Object|null} Returns a new chosen font object or `null` if font was not selected.
+     */
+    chooseFont(title?: string, initial_font?: Object): Object | null;
+    /**
+     * Sets or get a window state. Use one of these enum values: Window.State.[Normal|Minimized|Maximized|MaximizedHorizontally|MaximizedVertically]
+     *
+     * @param {Window.State} [state] - Setting new window state
+     * @returns {Window.State|Window} Returns `this` Window if argument is provided, otherwise returns current state.
+     * @see Window#State
+     * @example
+     * window.state(Window.State.Maximized);
+     * if(window.state() === Window.State.Maximized) console.log("It works!");
+     */
+    state(...args: any[]): Readonly<{
+        Normal: 0;
+        Minimized: 1;
+        Maximized: 2;
+        MaximizedHorizontally: 3;
+        MaximizedVertically: 4;
+    }> | Window;
+    /**
+     * Convenience method to minimize the Window by setting Window state to Window.State.Minimized.
+     *
+     * @return {Window} Returns `this` Window.
+     * @see Window#State
+     * @see Window#state
+     * @see Window#maximize
+     */
+    minimize(): Window;
+    /**
+     * Convenience method to maximize the Window by setting Window state to Window.State.Maximized.
+     *
+     * @return {Window} Returns `this` Window.
+     * @see Window#State
+     * @see Window#state
+     * @see Window#minimize
+     */
+    maximize(): Window;
+    /**
+     * Sets or returns the index or the screen that the Window is on.
+     *
+     * @args {number} [index] - Index of the screen where to move this Window. To get a list of screens with indexes use ui.screens().
+     * @return {Window|number} Returns `this` Window if argument is provided, otherwise returns index of the screen this Window is on.
+     */
+    screen(...args: any[]): Window | number;
+    /**
+     * Sets or gets a default button in this window form. On some systems like Windows OS default button has a different look than other buttons.
+     *
+     * @param {Button} button - The button that should be default on this Window. Only last assigned button gets to be default.
+     * @return {Button|undefined}
+     */
+    defaultButton(...args: any[]): Button | undefined;
+    /**
+     * Sets or gets a size of content container of this Window (doesn't include the size of the window borders and a menu bar like size() function does).
+     *
+     * @param {number|Size} [width_or_size] - Width integer or a Size object as a sole parameter.
+     * @param {number} [height] - Integer height value (required if the first argument is a numeric width).
+     * @return {Size|Window} Returns `this` Window if called with parameters, otherwise returns the inner size.
+     * @see Size
+     */
+    innerSize(...args: any[]): Size | Window;
+    /**
+     * Indicates the minimum size the content container of the Window it can be resized to. It overrides previously set minSize() value.
+     *
+     * @param {number|Size} width_or_size - Width, or a Size formatted object as a sole parameter.
+     * @param {number} height - Height of the component.
+     * @returns {Size|Window|null} If called without parameters, current minimum inner Size is returned or `null` if it wasn't previously set; otherwise returns `this` component instance for chaining.
+     * @see Window#maxInnerSize
+     * @see UIComponent#minSize
+     * @see Size
+     */
+    minInnerSize(...args: any[]): Size | Window | null;
+    /**
+     * Indicates the maximum size the content container of the Window it can be resized to. It overrides previously set maxSize() value.
+     *
+     * @param {number|Size} width_or_size - Width, or a Size formatted object as a sole parameter.
+     * @param {number} height - Height of the component.
+     * @returns {Size|Window|null} If called without parameters, current maximum inner Size is returned or `null` if it wasn't previously set; otherwise returns `this` component instance for chaining.
+     * @see Window#minInnerSize
+     * @see UIComponent#maxSize
+     * @see Size
+     */
+    maxInnerSize(...args: any[]): Size | Window | null;
+    /**
+     * Sets or gets whether window should always stay on top of other windows.
+     *
+     * @param {boolean} [value] - Set Window to be on top or not
+     * @return {Window|boolean} Returns `this` Window if arguments are supplied, otherwise returns `boolean` value.
+     */
+    alwaysOnTop(...args: any[]): Window | boolean;
+    /**
+     * Sets or gets the main menu bar for the top of the Window. On macOS, this menu bar appears in the system's top menu bar.
+     *
+     * @param {MenuBar} [bar] - The `MenuBar` to set as the primary menu bar.
+     * @returns {Window|MenuBar|null} Returns the `Window` instance when setting a menu bar; otherwise, returns the currently set `MenuBar`, or `null` if none is set.
+     */
+    menuBar(...args: any[]): Window | MenuBar | null;
+    /**
+     * Sets of get whether the window may be resized by end user.
+     *
+     * @param {boolean} [value] - Enables/disables resizing
+     * @return {Window|boolean} Returns `this` Window if argument is supplied, otherwise returns `boolean` value.
+     */
+    resizable(...args: any[]): Window | boolean;
+    /**
+     * Sets or gets component opacity float value between 0 and 1 inclusive. Opacity can be set only to Windo with types {@link Window.Type.Borderless} or {@link Window.Type.Popup}.
+     *
+     * @param {number} [opacity] - A number between 0 and 1 inclusive.
+     * @return {number|this} If `opacity` argument is provided, `this` component is returned, otherwise opacity `number` is returned.
+     */
+    opacity(...args: any[]): number | this;
+    #private;
+}
+import { ShapeContainer } from "./ShapeContainer.js";