obsidian-dev-utils/dist/lib/esm/obsidian/Plugin/PluginBase.d.mts

This is the collection of useful functions that you can use for your Obsidian plugin development

/**
 * @packageDocumentation
 *
 * Base class for Obsidian plugins providing utility methods for settings management, error handling, and notifications.
 *
 * This class simplifies the process of managing plugin settings, displaying notifications, and handling errors.
 * Subclasses should implement methods to create default settings and settings tabs, and complete plugin-specific
 * loading tasks.
 */
import type { ReadonlyDeep } from 'type-fest';
import { Plugin as ObsidianPlugin } from 'obsidian';
import type { TranslationsMap } from '../i18n/i18n.mjs';
import type { ExtractPluginSettings, ExtractPluginSettingsManager, ExtractPluginSettingsTab, ExtractReadonlyPluginSettingsWrapper, PluginTypesBase } from './PluginTypesBase.mjs';
import { AsyncEvents } from '../../AsyncEvents.mjs';
type LifecycleEventName = 'layoutReady' | 'load' | 'unload';
/**
 * Base class for creating Obsidian plugins with built-in support for settings management, error handling, and notifications.
 *
 * @typeParam PluginTypes - Plugin-specific types.
 */
export declare abstract class PluginBase<PluginTypes extends PluginTypesBase> extends ObsidianPlugin {
    readonly events: AsyncEvents;
    /**
     * Gets the AbortSignal used for aborting long-running operations.
     *
     * @returns The abort signal.
     */
    get abortSignal(): AbortSignal;
    /**
     * Gets the readonly plugin settings.
     *
     * @returns The readonly plugin settings.
     */
    get settings(): ReadonlyDeep<ExtractPluginSettings<PluginTypes>>;
    /**
     * Gets the plugin settings manager.
     *
     * @returns The plugin settings manager.
     */
    get settingsManager(): ExtractPluginSettingsManager<PluginTypes>;
    /**
     * Gets the plugin settings tab.
     *
     * @returns The plugin settings tab.
     */
    get settingsTab(): ExtractPluginSettingsTab<PluginTypes>;
    private _abortSignal;
    private _settingsManager;
    private _settingsTab;
    private readonly lifecycleEventNames;
    private notice?;
    /**
     * Logs a message to the console.
     *
     * Use instead of `console.debug()`.
     *
     * Those messages are not shown by default, but they can be shown by enabling `your-plugin-id` debugger namespace.
     *
     * @see {@link https://github.com/mnaoumov/obsidian-dev-utils/blob/main/docs/debugging.md} for more information.
     *
     * @param message - The message to log.
     * @param args - The arguments to log.
     */
    consoleDebug(message: string, ...args: unknown[]): void;
    /**
     * Called when the external settings change.
     *
     * Usually, you don't need to override this method. Consider using {@link onLoadSettings} instead.
     *
     * If you still need to override this method, make sure to call `await super.onExternalSettingsChange()` first.
     */
    onExternalSettingsChange(): Promise<void>;
    /**
     * Called when the plugin is loaded
     *
     * Usually, you don't need to override this method. Consider using {@link onloadImpl} instead.
     *
     * If you still need to override this method, make sure to call `await super.onload()` first.
     */
    onload(): Promise<void>;
    /**
     * Called when the plugin is unloaded.
     *
     * Usually, you don't need to override this method. Consider using {@link onunloadImpl} instead.
     *
     * If you still need to override this method, make sure to call `super.onunload()` first.
     */
    onunload(): void;
    /**
     * Registers a DOM window handler.
     *
     * @param domWindowHandler - The DOM window handler.
     */
    registerDomWindowHandler(domWindowHandler: (win: Window) => void): void;
    /**
     * Registers a callback to be executed when a lifecycle event is triggered.
     *
     * @param name - The name of the event.
     * @param callback - The callback to execute.
     */
    registerForLifecycleEvent(name: LifecycleEventName, callback: () => Promise<void>): void;
    /**
     * Registers a DOM event for all popup window documents.
     *
     * @typeParam DocumentEventType - The type of the event.
     * @param type - The type of the event.
     * @param callback - The callback to execute.
     * @param options - The options for the event.
     */
    registerPopupDocumentDomEvent<DocumentEventType extends keyof DocumentEventMap>(type: DocumentEventType, callback: (this: HTMLElement, evt: DocumentEventMap[DocumentEventType]) => unknown, options?: AddEventListenerOptions | boolean): void;
    /**
     * Registers a DOM event for all popup windows.
     *
     * @typeParam WindowEventType - The type of the event.
     * @param type - The type of the event.
     * @param callback - The callback to execute.
     * @param options - The options for the event.
     */
    registerPopupWindowDomEvent<WindowEventType extends keyof WindowEventMap>(type: WindowEventType, callback: (this: HTMLElement, evt: WindowEventMap[WindowEventType]) => unknown, options?: AddEventListenerOptions | boolean): void;
    /**
     * Waits for a lifecycle event to be triggered.
     *
     * If you `await` this method during lifecycle event, it might cause a deadlock.
     *
     * Consider wrapping this call with {@link invokeAsyncSafely}.
     *
     * @param name - The name of the event.
     * @returns A {@link Promise} that resolves when the event is triggered.
     */
    waitForLifecycleEvent(name: LifecycleEventName): Promise<void>;
    /**
     * Creates the plugin settings manager. This method must be implemented by subclasses.
     *
     * @returns The plugin settings manager.
     */
    protected createSettingsManager(): ExtractPluginSettingsManager<PluginTypes> | null;
    /**
     * Creates a plugin settings tab.
     *
     * @returns The settings tab or null if not applicable.
     */
    protected createSettingsTab(): ExtractPluginSettingsTab<PluginTypes> | null;
    /**
     * Creates a translations map.
     *
     * @returns The translations map.
     */
    protected createTranslationsMap(): TranslationsMap<PluginTypes>;
    /**
     * Called when an async error occurs.
     *
     * @param _asyncError - The async error.
     */
    protected handleAsyncError(_asyncError: unknown): void;
    /**
     * Called when the layout is ready.
     */
    protected onLayoutReady(): Promise<void>;
    /**
     * Executed when the plugin is loaded.
     *
     * If this method fails, the plugin will be automatically unloaded.
     *
     * @remarks It is important to call `super.onloadImpl()` in overridden method.
     */
    protected onloadImpl(): Promise<void>;
    /**
     * Called when the plugin settings are loaded or reloaded.
     *
     * @param _loadedSettings - The loaded settings wrapper.
     * @param _isInitialLoad - Whether the settings are being loaded for the first time.
     */
    protected onLoadSettings(_loadedSettings: ExtractReadonlyPluginSettingsWrapper<PluginTypes>, _isInitialLoad: boolean): Promise<void>;
    /**
     * Called when the plugin settings are saved.
     *
     * @param _newSettings - The new settings.
     * @param _oldSettings - The old settings.
     * @param _context - The context.
     */
    protected onSaveSettings(_newSettings: ExtractReadonlyPluginSettingsWrapper<PluginTypes>, _oldSettings: ExtractReadonlyPluginSettingsWrapper<PluginTypes>, _context: unknown): Promise<void>;
    /**
     * Called when the plugin is unloaded.
     */
    protected onunloadImpl(): Promise<void>;
    /**
     * Displays a notice message to the user.
     *
     * @param message - The message to display.
     */
    protected showNotice(message: string): void;
    private afterLoad;
    private onLayoutReadyBase;
    private triggerLifecycleEvent;
}
export {};