tiny-electron-essentials
Version:
A lightweight and modular utility library for Electron apps, offering simplified window management, tray support, IPC channels, and custom frameless window styling.
341 lines • 15.8 kB
text/typescript
export default TinyWinInstance;
/**
* Represents a single managed Electron BrowserWindow instance.
*
* This class tracks visibility, readiness, and index of the window.
* It allows toggling visibility and storing references to the parent controller and window instance.
*/
declare class TinyWinInstance {
/**
* @param {Object} [settings2={}] - Configuration for the new instance.
* @param {Emit} [settings2.emit] - The root controller or application class managing this instance.
* @param {SetProxy} [settings2.setProxy] - SetProxy callback.
* @param {OpenDevTools} [settings2.openDevTools] - OpenDevTools callback.
* @param {LoadPath} [settings2.loadPath] - Load path callback.
* @param {AppEvents} [settings2.eventNames=this.#AppEvents] - Set of event names for internal messaging.
* @param {Object} [settings={}] - Configuration for the new BrowserWindow.
* @param {Electron.BrowserWindowConstructorOptions} [settings.config] - Configuration for the new BrowserWindow.
* @param {string|number} [settings.index] - (Optional) Index of the window in the manager.
* @param {boolean} [settings.isMaximized=false] - The window will try to be maximized by booting.
* @param {boolean} [settings.openWithBrowser=true] - if you will make all links open with the browser, not with the application.
* @param {boolean} [settings.show] - The window will appear when the load is finished.
* @param {string[]} [settings.urls=['https:', 'http:']] - List of allowed URL protocols to permit external opening.
* @throws {Error} If any parameter is invalid.
*/
constructor({ eventNames, emit, loadPath, openDevTools, setProxy }?: {
emit?: ((arg0: string | symbol, ...arg1: any[]) => void) | undefined;
setProxy?: ((win: Electron.BrowserWindow, config: Electron.ProxyConfig) => void) | undefined;
openDevTools?: ((win: Electron.BrowserWindow, ops?: Electron.OpenDevToolsOptions) => void) | undefined;
loadPath?: ((win: Electron.BrowserWindow, page: string | string[], ops?: Electron.LoadFileOptions | Electron.LoadURLOptions) => void) | undefined;
eventNames?: AppEvents | undefined;
}, { config, index, show, isMaximized, openWithBrowser, urls, }?: {
config?: Electron.BrowserWindowConstructorOptions | undefined;
index?: string | number | undefined;
isMaximized?: boolean | undefined;
openWithBrowser?: boolean | undefined;
show?: boolean | undefined;
urls?: string[] | undefined;
});
/**
* Provides access to a secure internal EventEmitter for subclass use only.
*
* This method exposes a dedicated EventEmitter instance intended specifically for subclasses
* that extend the main class. It prevents subclasses from accidentally or intentionally using
* the primary class's public event system (`emit`), which could lead to unpredictable behavior
* or interference in the base class's event flow.
*
* For security and consistency, this method is designed to be accessed only once.
* Multiple accesses are blocked to avoid leaks or misuse of the internal event bus.
*
* @returns {EventEmitter} A special internal EventEmitter instance for subclass use.
* @throws {Error} If the method is called more than once.
*/
getSysEvents(): EventEmitter;
/**
* @typedef {(...args: any[]) => void} ListenerCallback
* A generic callback function used for event listeners.
*/
/**
* Sets the maximum number of listeners for the internal event emitter.
*
* @param {number} max - The maximum number of listeners allowed.
*/
setMaxListeners(max: number): void;
/**
* Emits an event with optional arguments.
* @param {string | symbol} event - The name of the event to emit.
* @param {...any} args - Arguments passed to event listeners.
* @returns {boolean} `true` if the event had listeners, `false` otherwise.
*/
emit(event: string | symbol, ...args: any[]): boolean;
/**
* Registers a listener for the specified event.
* @param {string | symbol} event - The name of the event to listen for.
* @param {ListenerCallback} listener - The callback function to invoke.
* @returns {this} The current class instance (for chaining).
*/
on(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Registers a one-time listener for the specified event.
* @param {string | symbol} event - The name of the event to listen for once.
* @param {ListenerCallback} listener - The callback function to invoke.
* @returns {this} The current class instance (for chaining).
*/
once(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Removes a listener from the specified event.
* @param {string | symbol} event - The name of the event.
* @param {ListenerCallback} listener - The listener to remove.
* @returns {this} The current class instance (for chaining).
*/
off(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Alias for `on`.
* @param {string | symbol} event - The name of the event.
* @param {ListenerCallback} listener - The callback to register.
* @returns {this} The current class instance (for chaining).
*/
addListener(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Alias for `off`.
* @param {string | symbol} event - The name of the event.
* @param {ListenerCallback} listener - The listener to remove.
* @returns {this} The current class instance (for chaining).
*/
removeListener(event: string | symbol, listener: (...args: any[]) => void): this;
/**
* Removes all listeners for a specific event, or all events if no event is specified.
* @param {string | symbol} [event] - The name of the event. If omitted, all listeners from all events will be removed.
* @returns {this} The current class instance (for chaining).
*/
removeAllListeners(event?: string | symbol): this;
/**
* Returns the number of times the given `listener` is registered for the specified `event`.
* If no `listener` is passed, returns how many listeners are registered for the `event`.
* @param {string | symbol} eventName - The name of the event.
* @param {Function} [listener] - Optional listener function to count.
* @returns {number} Number of matching listeners.
*/
listenerCount(eventName: string | symbol, listener?: Function): number;
/**
* Adds a listener function to the **beginning** of the listeners array for the specified event.
* The listener is called every time the event is emitted.
* @param {string | symbol} eventName - The event name.
* @param {ListenerCallback} listener - The callback function.
* @returns {this} The current class instance (for chaining).
*/
prependListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
/**
* Adds a **one-time** listener function to the **beginning** of the listeners array.
* The next time the event is triggered, this listener is removed and then invoked.
* @param {string | symbol} eventName - The event name.
* @param {ListenerCallback} listener - The callback function.
* @returns {this} The current class instance (for chaining).
*/
prependOnceListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
/**
* Returns an array of event names for which listeners are currently registered.
* @returns {(string | symbol)[]} Array of event names.
*/
eventNames(): (string | symbol)[];
/**
* Gets the current maximum number of listeners allowed for any single event.
* @returns {number} The max listener count.
*/
getMaxListeners(): number;
/**
* Returns a copy of the listeners array for the specified event.
* @param {string | symbol} eventName - The event name.
* @returns {Function[]} An array of listener functions.
*/
listeners(eventName: string | symbol): Function[];
/**
* Returns a copy of the internal listeners array for the specified event,
* including wrapper functions like those used by `.once()`.
* @param {string | symbol} eventName - The event name.
* @returns {Function[]} An array of raw listener functions.
*/
rawListeners(eventName: string | symbol): Function[];
/**
* Checks if a given value exists in the AppEvents values.
*
* @param {string} value - The value to check for.
* @returns {boolean} True if the value exists, false otherwise.
*/
isValidAppEvent(value: string): boolean;
/**
* Gets the key (event name) associated with a given AppEvents value.
*
* @param {string} value - The value to look up.
* @returns {string} The matching AppEvents key.
* @throws {Error} If the value is not found.
*/
getAppEventKey(value: string): string;
/**
* Returns whether the window is currently maximizable.
*
* @returns {boolean} True if the window can be maximized; otherwise, false.
*/
isMaximizable(): boolean;
/**
* Returns whether the window is currently closable.
*
* @returns {boolean} True if the window can be closed; otherwise, false.
*/
isClosable(): boolean;
/**
* Returns whether the window is currently fullscreenable.
*
* @returns {boolean} True if the window can enter fullscreen; otherwise, false.
*/
isFullScreenable(): boolean;
/**
* Returns whether the window is currently focusable.
*
* @returns {boolean} True if the window can be focused; otherwise, false.
*/
isFocusable(): boolean;
/**
* Returns the window index assigned to this instance.
* @returns {string|number|null}
*/
getIndex(): string | number | null;
/**
* Checks whether the window is currently visible.
* @returns {boolean}
*/
isVisible(): boolean;
/**
* Checks whether the window is marked as ready.
* @returns {boolean}
*/
isReady(): boolean;
/**
* Loads a page. Depending on configuration, it can load a local file path or a URL.
*
* @param {string|string[]} page - The page or path segments to load.
* @param {Electron.LoadFileOptions|Electron.LoadURLOptions} [ops] - Options passed to `loadFile` or `loadURL`.
* @throws {TypeError} If page is not a string or string[].
* @throws {TypeError} If page contains non-string entries.
* @throws {TypeError} If ops is not an object.
*/
loadPath(page: string | string[], ops?: Electron.LoadFileOptions | Electron.LoadURLOptions): void;
/**
* Opens the developer tools.
* Also sends the custom console warning message to the devtools console.
* @param {Electron.OpenDevToolsOptions} [ops] - The target DevTools config.
*/
openDevTools(ops?: Electron.OpenDevToolsOptions): void;
/**
* Sets whether the window can be maximized.
* Sends an event to the renderer with the updated state.
*
* @param {boolean} value - If true, the window becomes maximizable; otherwise, it cannot be maximized.
* @returns {boolean} - Edit result.
*/
setMaximizable(value: boolean): boolean;
/**
* Sets whether the window can be closed.
* Sends an event to the renderer with the updated state.
*
* @param {boolean} value - If true, the window can be closed; otherwise, it cannot be closed.
* @returns {boolean} - Edit result.
*/
setClosable(value: boolean): boolean;
/**
* Sets whether the window can be focused.
* Sends an event to the renderer with the updated state.
*
* @param {boolean} value - If true, the window can be focused; otherwise, it cannot receive focus.
* @returns {boolean} - Edit result.
*/
setFocusable(value: boolean): boolean;
/**
* Sets whether the window can enter fullscreen mode.
* Sends an event to the renderer with the updated state.
*
* @param {boolean} value - If true, the window can enter fullscreen mode; otherwise, it cannot receive focus.
* @returns {boolean} - Edit result.
*/
setFullScreenable(value: boolean): boolean;
/**
* Applies a network proxy configuration.
*
* This method sets the proxy settings for the session.
* Upon completion, it emits events back to the renderer process to indicate success or failure.
*
* @param {Electron.ProxyConfig} config - The proxy configuration object following Electron's ProxyConfig structure.
* Example: `{ proxyRules: 'http=myproxy.com:8080;https=myproxy.com:8080', proxyBypassRules: 'localhost' }`
*
* @throws {Error} Throws an error if the provided window (`win`) is invalid (null, destroyed, or missing webContents).
*
* @returns {void}
*/
setProxy(config: Electron.ProxyConfig): void;
/**
* Returns the internal BrowserWindow instance.
* @returns {BrowserWindow}
* @throws {Error} If the window is not initialized.
*/
getWin(): BrowserWindow;
/**
* Toggles the visibility of the window, or sets it explicitly if a value is provided.
*
* Emits the `ShowApp` event to the root instance when visibility changes.
*
* @param {boolean} [isVisible] - If defined, sets visibility to this value. Otherwise, it toggles.
* @returns {boolean} - The new visibility state.
* @throws {Error} If `isVisible` is not a boolean or undefined.
*/
toggleVisible(isVisible?: boolean): boolean;
/**
* Sends a ping event with custom data to the renderer process.
*
* This method allows the main process to send arbitrary data to the window
* via the `Ping` event. It is commonly used for connection checks,
* heartbeat signals, or simple data synchronization.
*
* @param {any} data - Any serializable data to send along with the ping event.
*
* @throws {Error} Throws an error if the window instance is destroyed or unavailable.
*
* @returns {void}
*/
ping(data: any): void;
/**
* Checks whether the given IPC event originated from this window instance.
*
* This is useful when multiple windows exist and you want to ensure an IPC event
* came from the correct one before handling it.
*
* @param {Electron.IpcMainEvent} event - The IPC event object received in the main process.
* @returns {boolean} - Returns true if the event originated from this instance's window.
*/
isFromWin(event: Electron.IpcMainEvent): boolean;
/**
* Checks whether the internal BrowserWindow instance has been destroyed.
*
* This method safely verifies if the window no longer exists or has already been destroyed.
* It handles edge cases where the window may be `null` or the `isDestroyed` method is unavailable.
*
* @returns {boolean} `true` if the window is destroyed or unavailable, otherwise `false`.
*/
isDestroyed(): boolean;
/**
* Checks whether the internal BrowserWindow instance is preparing to be destroyed.
*
* @returns {boolean} `true` if the window is being destroyed.
*/
isPreparingDestroy(): boolean;
/**
* Destroys the current BrowserWindow instance.
*
* @returns {void}
*/
destroy(): void;
#private;
}
import { EventEmitter } from 'events';
import { BrowserWindow } from 'electron';
import { AppEvents } from '../global/Events.mjs';
//# sourceMappingURL=TinyWinInstance.d.mts.map