@mlightcad/cad-simple-viewer 1.0.0 → 1.0.2

package/lib/app/AcApDocManager.d.ts

@@ -2,59 +2,274 @@ import { AcCmEventManager, AcDbOpenDatabaseOptions } from '@mlightcad/data-model
 import { AcTrView2d } from '../view';
 import { AcApContext } from './AcApContext';
 import { AcApDocument } from './AcApDocument';
+/**
+ * Event arguments for document-related events.
+ */
 export interface AcDbDocumentEventArgs {
+    /** The document involved in the event */
     doc: AcApDocument;
 }
+/**
+ * Document manager that handles CAD document lifecycle and provides the main entry point for the CAD viewer.
+ *
+ * This singleton class manages:
+ * - Document creation and opening (from URLs or file content)
+ * - View and context management
+ * - Command registration and execution
+ * - Font loading for text rendering
+ * - Event handling for document lifecycle
+ *
+ * The manager follows a singleton pattern to ensure only one instance manages the application state.
+ */
 export declare class AcApDocManager {
+    /** The current application context binding document and view */
     private _context;
+    /** Font loader for managing CAD text fonts */
     private _fontLoader;
+    /** Singleton instance */
     private static _instance?;
+    /** Events fired during document lifecycle */
     readonly events: {
+        /** Fired when a new document is created */
         documentCreated: AcCmEventManager<AcDbDocumentEventArgs>;
+        /** Fired when a document becomes active */
         documentActivated: AcCmEventManager<AcDbDocumentEventArgs>;
     };
+    /**
+     * Private constructor for singleton pattern.
+     *
+     * Creates an empty document with a 2D view and sets up the application context.
+     * Registers default commands and creates an example document.
+     *
+     * @param canvas - Optional HTML canvas element for rendering. If not provided, a new canvas will be created
+     * @private
+     */
     private constructor();
+    /**
+     * Creates the singleton instance with an optional canvas element.
+     *
+     * This method should be called before accessing the `instance` property
+     * if you want to provide a specific canvas element.
+     *
+     * @param canvas - Optional HTML canvas element for rendering
+     * @returns The singleton instance
+     *
+     * @example
+     * ```typescript
+     * const canvas = document.getElementById('my-canvas') as HTMLCanvasElement;
+     * const docManager = AcApDocManager.createInstance(canvas);
+     * ```
+     */
     static createInstance(canvas?: HTMLCanvasElement): AcApDocManager | undefined;
+    /**
+     * Gets the singleton instance of the document manager.
+     *
+     * Creates a new instance if one doesn't exist yet.
+     *
+     * @returns The singleton document manager instance
+     */
     static get instance(): AcApDocManager;
     /**
-     * Current context
+     * Gets the current application context.
+     *
+     * The context binds the current document with its associated view.
+     *
+     * @returns The current application context
      */
     get context(): AcApContext;
     /**
-     * Current open drawing
+     * Gets the currently open CAD document.
+     *
+     * @returns The current document instance
      */
     get curDocument(): AcApDocument;
     /**
-     * For now, it is same as property `curDocument`.
+     * Gets the currently active document.
+     *
+     * For now, this is the same as `curDocument` since only one document
+     * can be active at a time.
+     *
+     * @returns The current active document
      */
     get mdiActiveDocument(): AcApDocument;
     /**
-     * Current view used to show current drawing
+     * Gets the current 2D view used to display the drawing.
+     *
+     * @returns The current 2D view instance
      */
     get curView(): AcTrView2d;
+    /**
+     * Gets the editor instance for handling user input.
+     *
+     * @returns The current editor instance
+     */
     get editor(): import("../editor").AcEditor;
     /**
-     * Avaiable fonts to load. It means those fonts are avaiable to load. However, it
-     * doesn't mean those fonts are already loaded and avaiable to use.
+     * Gets the list of available fonts that can be loaded.
+     *
+     * Note: These fonts are available for loading but may not be loaded yet.
+     *
+     * @returns Array of available font names
      */
     get avaiableFonts(): import("@mlightcad/data-model").AcDbFontInfo[];
     /**
-     * Load the specified fonts
-     * @param fonts Input one list of font names
+     * Loads the specified fonts for text rendering.
+     *
+     * @param fonts - Array of font names to load
+     * @returns Promise that resolves when fonts are loaded
+     *
+     * @example
+     * ```typescript
+     * await docManager.loadFonts(['Arial', 'Times New Roman']);
+     * ```
      */
     loadFonts(fonts: string[]): Promise<void>;
     /**
-     * Load default fonts
+     * Loads default fonts for CAD text rendering.
+     *
+     * This method loads either the specified fonts or falls back to default Chinese fonts
+     * (specifically 'simkai') if no fonts are provided. The loaded fonts are used for
+     * rendering CAD text entities like MText and Text in the viewer.
+     *
+     * It is better to load default fonts when viewer is initialized so that the viewer can
+     * render text correctly if fonts used in the document are not available.
+     *
+     * @param fonts - Optional array of font names to load. If not provided or null,
+     *               defaults to ['simkai'] for Chinese text support
+     * @returns Promise that resolves when all specified fonts are loaded
+     *
+     * @example
+     * ```typescript
+     * // Load default fonts (simkai)
+     * await docManager.loadDefaultFonts();
+     *
+     * // Load specific fonts
+     * await docManager.loadDefaultFonts(['Arial', 'SimSun']);
+     *
+     * // Load no fonts (empty array)
+     * await docManager.loadDefaultFonts([]);
+     * ```
+     *
+     * @see {@link AcApFontLoader.load} - The underlying font loading implementation
+     * @see {@link createExampleDoc} - Method that uses this for example document creation
+     */
+    loadDefaultFonts(fonts?: string[]): Promise<void>;
+    /**
+     * Creates an example CAD document with sample content.
+     *
+     * This method asynchronously loads default fonts, creates example drawing content,
+     * sets up layout information, and zooms the view to fit the content.
+     * The creation is performed after a short delay to ensure proper initialization.
      */
-    loadDefaultFonts(): Promise<void>;
     createExampleDoc(): void;
-    openUrl(url: string, options?: AcDbOpenDatabaseOptions): Promise<void>;
-    openDocument(fileName: string, content: string | ArrayBuffer, options: AcDbOpenDatabaseOptions): Promise<void>;
+    /**
+     * Opens a CAD document from a URL.
+     *
+     * This method loads a document from the specified URL and replaces the current document.
+     * It handles the complete document lifecycle including before/after open events.
+     *
+     * @param url - The URL of the CAD file to open
+     * @param options - Optional database opening options. If not provided, default options with font loader will be used
+     * @returns Promise that resolves to true if the document was successfully opened, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const success = await docManager.openUrl('https://example.com/drawing.dwg');
+     * if (success) {
+     *   console.log('Document opened successfully');
+     * }
+     * ```
+     */
+    openUrl(url: string, options?: AcDbOpenDatabaseOptions): Promise<boolean>;
+    /**
+     * Opens a CAD document from file content.
+     *
+     * This method loads a document from the provided file content (string or binary data)
+     * and replaces the current document. It handles the complete document lifecycle
+     * including before/after open events.
+     *
+     * @param fileName - The name of the file being opened (used for format detection)
+     * @param content - The file content as string or ArrayBuffer
+     * @param options - Database opening options including font loader settings
+     * @returns Promise that resolves to true if the document was successfully opened, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const fileContent = await file.arrayBuffer();
+     * const success = await docManager.openDocument('drawing.dwg', fileContent, options);
+     * ```
+     */
+    openDocument(fileName: string, content: string | ArrayBuffer, options: AcDbOpenDatabaseOptions): Promise<boolean>;
+    /**
+     * Registers all default commands available in the CAD viewer.
+     *
+     * This method sets up the command system by registering built-in commands including:
+     * - pan: Pan/move the view
+     * - select: Select entities
+     * - zoom: Zoom in/out
+     * - zoomw: Zoom to window/box
+     * - csvg: Convert to SVG
+     * - qnew: Quick new document
+     * - open: Open document
+     *
+     * All commands are registered under the system command group.
+     */
     registerCommands(): void;
+    /**
+     * Executes a command by its string name.
+     *
+     * This method looks up a registered command by name and executes it with the current context.
+     * If the command is not found, no action is taken.
+     *
+     * @param cmdStr - The command string to execute (e.g., 'pan', 'zoom', 'select')
+     *
+     * @example
+     * ```typescript
+     * docManager.sendStringToExecute('zoom');
+     * docManager.sendStringToExecute('pan');
+     * ```
+     */
     sendStringToExecute(cmdStr: string): void;
+    /**
+     * Performs cleanup operations before opening a new document.
+     *
+     * This protected method is called automatically before any document opening operation.
+     * It clears the current view to prepare for the new document content.
+     *
+     * @protected
+     */
     protected onBeforeOpenDocument(): void;
+    /**
+     * Performs setup operations after a document opening attempt.
+     *
+     * This protected method is called automatically after any document opening operation.
+     * If the document was successfully opened, it dispatches the documentActivated event,
+     * sets up layout information, and zooms the view to fit the content.
+     *
+     * @param isSuccess - Whether the document was successfully opened
+     * @protected
+     */
     protected onAfterOpenDocument(isSuccess: boolean): void;
+    /**
+     * Sets up or validates database opening options.
+     *
+     * This private method ensures that the options object has a font loader configured.
+     * If no options are provided, creates new options with the font loader.
+     * If options are provided but missing a font loader, adds the font loader.
+     *
+     * @param options - Optional database opening options to validate/modify
+     * @returns The validated options object with font loader configured
+     * @private
+     */
     private setOptions;
+    /**
+     * Configures layout information for the current view.
+     *
+     * This private method sets up the active layout block table record ID and
+     * model space block table record ID based on the current document's space configuration.
+     *
+     * @private
+     */
     private setLayoutInfo;
 }
 //# sourceMappingURL=AcApDocManager.d.ts.map

package/lib/app/AcApDocManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AcApDocManager.d.ts","sourceRoot":"","sources":["../../src/app/AcApDocManager.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAEhB,uBAAuB,EACxB,MAAM,uBAAuB,CAAA;AAa9B,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG7C,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,YAAY,CAAA;CAClB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAgB;IAEzC,SAAgB,MAAM;;;MAGrB;IAED,OAAO;IAwBP,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,iBAAiB;IAOhD,MAAM,KAAK,QAAQ,mBAKlB;IAED;;OAEG;IACH,IAAI,OAAO,gBAEV;IAED;;OAEG;IACH,IAAI,WAAW,iBAEd;IAED;;OAEG;IACH,IAAI,iBAAiB,iBAEpB;IAED;;OAEG;IACH,IAAI,OAAO,IACoB,UAAU,CACxC;IAED,IAAI,MAAM,iCAET;IAED;;;OAGG;IACH,IAAI,aAAa,mDAEhB;IAED;;;OAGG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE;IAI/B;;OAEG;IACG,gBAAgB;IAMtB,gBAAgB;IASV,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB;IAQtD,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,WAAW,EAC7B,OAAO,EAAE,uBAAuB;IAalC,gBAAgB;IA8ChB,mBAAmB,CAAC,MAAM,EAAE,MAAM;IAMlC,SAAS,CAAC,oBAAoB;IAI9B,SAAS,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAO;IAUhD,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,aAAa;CAKtB"}
+{"version":3,"file":"AcApDocManager.d.ts","sourceRoot":"","sources":["../../src/app/AcApDocManager.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAEhB,uBAAuB,EACxB,MAAM,uBAAuB,CAAA;AAa9B,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG7C;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,GAAG,EAAE,YAAY,CAAA;CAClB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;IACzB,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAa;IAC7B,8CAA8C;IAC9C,OAAO,CAAC,WAAW,CAAgB;IACnC,yBAAyB;IACzB,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAgB;IAEzC,6CAA6C;IAC7C,SAAgB,MAAM;QACpB,2CAA2C;;QAE3C,2CAA2C;;MAE5C;IAED;;;;;;;;OAQG;IACH,OAAO;IAwBP;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,iBAAiB;IAOhD;;;;;;OAMG;IACH,MAAM,KAAK,QAAQ,mBAKlB;IAED;;;;;;OAMG;IACH,IAAI,OAAO,gBAEV;IAED;;;;OAIG;IACH,IAAI,WAAW,iBAEd;IAED;;;;;;;OAOG;IACH,IAAI,iBAAiB,iBAEpB;IAED;;;;OAIG;IACH,IAAI,OAAO,IACoB,UAAU,CACxC;IAED;;;;OAIG;IACH,IAAI,MAAM,iCAET;IAED;;;;;;OAMG;IACH,IAAI,aAAa,mDAEhB;IAED;;;;;;;;;;OAUG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE;IAI/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE;IAQvC;;;;;;OAMG;IACH,gBAAgB;IAShB;;;;;;;;;;;;;;;;;OAiBG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB;IAS5D;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,WAAW,EAC7B,OAAO,EAAE,uBAAuB;IAclC;;;;;;;;;;;;;OAaG;IACH,gBAAgB;IA8ChB;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM;IAMlC;;;;;;;OAOG;IACH,SAAS,CAAC,oBAAoB;IAI9B;;;;;;;;;OASG;IACH,SAAS,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAO;IAUhD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,UAAU;IASlB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CAKtB"}