diff --git a/docs/API/attributes_functions_overview.md b/docs/API/attributes_functions_overview.md index 2cab073..6a3fd08 100644 --- a/docs/API/attributes_functions_overview.md +++ b/docs/API/attributes_functions_overview.md @@ -4,47 +4,56 @@ Here's the interface implemented by ExcalidrawAutomate: ```typescript ExcalidrawAutomate: { - plugin: ExcalidrawPlugin; - elementIds: []; - elementsDict: {}, - style: { - strokeColor: string; - backgroundColor: string; - angle: number; - fillStyle: FillStyle; - strokeWidth: number; - storkeStyle: StrokeStyle; - roughness: number; - opacity: number; - strokeSharpness: StrokeSharpness; - fontFamily: number; - fontSize: number; - textAlign: string; - verticalAlign: string; - startArrowHead: string; - endArrowHead: string; - } - canvas: {theme: string, viewBackgroundColor: string, gridSize: number}; - setFillStyle(val:number): void; - setStrokeStyle(val:number): void; - setStrokeSharpness(val:number): void; - setFontFamily(val:number): void; - setTheme(val:number): void; - addToGroup(objectIds:[]):void; - addRect(topX:number, topY:number, width:number, height:number):string; - addDiamond(topX:number, topY:number, width:number, height:number):string; - addEllipse(topX:number, topY:number, width:number, height:number):string; - addText(topX:number, topY:number, text:string, formatting?:{width?:number, height?:number,textAlign?: string, verticalAlign?:string, box?: boolean, boxPadding?: number},id?:string):string; - addLine(points: [[x:number,y:number]]):void; - addArrow(points: [[x:number,y:number]],formatting?:{startArrowHead:string,endArrowHead:string,startObjectId:string,endObjectId:string}):void ; - connectObjects(objectA: string, connectionA: ConnectionPoint, objectB: string, connectionB: ConnectionPoint, formatting?:{numberOfPoints: number,startArrowHead:string,endArrowHead:string, padding: number}):void; - toClipboard(templatePath?:string): void; - create(params?:{filename: string, foldername:string, templatePath:string, onNewPane: boolean}):Promise; - createSVG(templatePath?:string):Promise; - createPNG(templatePath?:string):Promise; - wrapText(text:string, lineLen:number):string; - clear(): void; - reset(): void; - isExcalidrawFile(f:TFile): boolean; +plugin: ExcalidrawPlugin; +elementsDict: {}; +style: { + strokeColor: string; + backgroundColor: string; + angle: number; + fillStyle: FillStyle; + strokeWidth: number; + storkeStyle: StrokeStyle; + roughness: number; + opacity: number; + strokeSharpness: StrokeSharpness; + fontFamily: number; + fontSize: number; + textAlign: string; + verticalAlign: string; + startArrowHead: string; + endArrowHead: string; +} +canvas: {theme: string, viewBackgroundColor: string, gridSize: number}; +setFillStyle(val:number): void; +setStrokeStyle(val:number): void; +setStrokeSharpness(val:number): void; +setFontFamily(val:number): void; +setTheme(val:number): void; +addToGroup(objectIds:[]):string; +toClipboard(templatePath?:string): void; +getElements():ExcalidrawElement[]; +getElement(id:string):ExcalidrawElement; +create(params?:{filename?: string, foldername?:string, templatePath?:string, onNewPane?: boolean}):Promise; +createSVG(templatePath?:string):Promise; +createPNG(templatePath?:string):Promise; +wrapText(text:string, lineLen:number):string; +addRect(topX:number, topY:number, width:number, height:number):string; +addDiamond(topX:number, topY:number, width:number, height:number):string; +addEllipse(topX:number, topY:number, width:number, height:number):string; +addText(topX:number, topY:number, text:string, formatting?:{width?:number, height?:number,textAlign?: string, verticalAlign?:string, box?: boolean, boxPadding?: number},id?:string):string; +addLine(points: [[x:number,y:number]]):string; +addArrow(points: [[x:number,y:number]],formatting?:{startArrowHead?:string,endArrowHead?:string,startObjectId?:string,endObjectId?:string}):string; +connectObjects(objectA: string, connectionA: ConnectionPoint, objectB: string, connectionB: ConnectionPoint, formatting?:{numberOfPoints?: number,startArrowHead?:string,endArrowHead?:string, padding?: number}):void; +clear(): void; +reset(): void; +isExcalidrawFile(f:TFile): boolean; +//view manipulation +targetView: ExcalidrawView; +setView(view:ExcalidrawView|"first"|"active"):ExcalidrawView; +getExcalidrawAPI():any; +getViewSelectedElement():ExcalidrawElement; +connectObjectWithViewSelectedElement(objectA:string,connectionA: ConnectionPoint, connectionB: ConnectionPoint, formatting?:{numberOfPoints?: number,startArrowHead?:string,endArrowHead?:string, padding?: number}):boolean; +addElementsToView(repositionToCursor:boolean, save:boolean):Promise; }; -``` \ No newline at end of file +``` + diff --git a/docs/API/objects.md b/docs/API/objects.md index 6a365df..a0f66e3 100644 --- a/docs/API/objects.md +++ b/docs/API/objects.md @@ -28,13 +28,15 @@ Returns the `id` of the object. The `id` is required when connecting objects wit ### addLine() ```typescript -addLine(points: [[x:number,y:number]]):void +addLine(points: [[x:number,y:number]]):string ``` Adds a line following the points provided. Must include at least two points `points.length >= 2`. If more than 2 points are provided the interim points will be added as breakpoints. The line will break with angles if `strokeSharpness` is set to "sharp" and will be curvey if it is set to "round". +Returns the `id` of the object. + ### addArrow() ```typescript -addArrow(points: [[x:number,y:number]],formatting?:{startArrowHead:string,endArrowHead:string,startObjectId:string,endObjectId:string}):void +addArrow(points: [[x:number,y:number]],formatting?:{startArrowHead?:string,endArrowHead?:string,startObjectId?:string,endObjectId?:string}):string ; ``` Adds an arrow following the points provided. Must include at least two points `points.length >= 2`. If more than 2 points are provided the interim points will be added as breakpoints. The line will break with angles if element `style.strokeSharpness` is set to "sharp" and will be curvey if it is set to "round". @@ -43,6 +45,8 @@ Adds an arrow following the points provided. Must include at least two points `p `startObjectId` and `endObjectId` are the object id's of connected objects. I recommend using `connectObjects` instead calling addArrow() for the purpose of connecting objects. +Returns the `id` of the object. + ### connectObjects() ```typescript declare type ConnectionPoint = "top"|"bottom"|"left"|"right"; @@ -60,6 +64,6 @@ Connects two objects with an arrow. ### addToGroup() ```typescript -addToGroup(objectIds:[]):void +addToGroup(objectIds:[]):string ``` -Groups objects listed in `objectIds`. \ No newline at end of file +Groups objects listed in `objectIds`. Returns the `id` of the group. \ No newline at end of file diff --git a/docs/API/utility.md b/docs/API/utility.md index 44a2e05..779906d 100644 --- a/docs/API/utility.md +++ b/docs/API/utility.md @@ -18,6 +18,19 @@ async toClipboard(templatePath?:string) ``` Places the generated drawing to the clipboard. Useful when you don't want to create a new drawing, but want to paste additional items onto an existing drawing. +### getElements() +```typescript +getElements():ExcalidrawElement[]; +``` +Returns the elements in ExcalidrawAutomate as an array of ExcalidrawElements. This format is usefull when working with ExcalidrawRef. + +### getElement() +```typescript +getElement(id:string):ExcalidrawElement; +``` + +Returns the element object matching the id. If the element does not exist, returns null. + ### create() ```typescript async create(params?:{filename: string, foldername:string, templatePath:string, onNewPane: boolean}) @@ -52,4 +65,57 @@ Returns a blob containing a PNG image of the generated drawing. ```typescript wrapText(text:string, lineLen:number):string ``` -Returns a string wrapped to the provided max lineLen. \ No newline at end of file +Returns a string wrapped to the provided max lineLen. + + +### Accessing the open Excalidraw view +You first need to initialize targetView, before using any of the view manipulation functions. + +#### targetView +```typescript +targetView: ExcalidrawView +``` +The open Excalidraw View configured as the target of the view operations. User `setView` to initialize. + +#### setView() +```typescript +setView(view:ExcalidrawView|"first"|"active"):ExcalidrawView +``` +Setting the ExcalidrawView that will be the target of the View operations. Valid `view` input values are: +- an object instance of ExcalidrawView +- "first": meaning if there are multiple Excalidraw Views open, pick the first that is returned by `app.workspace.getLeavesOfType("Excalidraw")` +- "active": meaning the currently active view + +#### getExcalidrawAPI() +```typescript +getExcalidrawAPI():any +``` +Returns the native Excalidraw API (ref.current) for the active drawing specified in `targetView`. +See Excalidraw documentation here: https://www.npmjs.com/package/@excalidraw/excalidraw#ref + +#### getViewSelectedElement() +```typescript +getViewSelectedElement():ExcalidrawElement +``` +If an element is selected in the targetView the function returns the selected element. If multiple elements are selected, either by SHIFT+Clicking to select multiple elements, or by selecting a group, the first of the elements will be selected. If you want to specify which element to select from a group, double click the desired element in the group. + +This function is helpful if you want to add a new element in relation to an existing element in your drawing. + +#### connectObjectWithViewSelectedElement() +```typescript +connectObjectWithViewSelectedElement(objectA:string,connectionA: ConnectionPoint, connectionB: ConnectionPoint, formatting?:{numberOfPoints?: number,startArrowHead?:string,endArrowHead?:string, padding?: number}):boolean +``` +Same as `connectObjects()`, but ObjectB is the currently selected element in the target ExcalidrawView. The function helps with placing an arrow between a newly created object and the selected element in the target ExcalidrawView. + +#### addElementsToView() +```typescript +addElementsToView(repositionToCursor:boolean=false, save:boolean=false):Promise +``` +Adds elements created with ExcalidrawAutomate to the target ExcalidrawView. +`repositionToCursor` dafault is false +- true: the elements will be moved such that the center point of the elements will be aligned with the current position of the pointer on ExcalidrawView. You can point and place elements to a desired location in your drawing using this switch. +- false: elements will be positioned as defined by the x&y coordinates of each element. + +`save` default is false +- true: the drawing will be saved after the elements were added. +- false: the drawing will be saved at the next autosave cycle. Use false when adding multiple elements one after the other. Else, best to use true, to minimize risk of data loss. \ No newline at end of file diff --git a/manifest.json b/manifest.json index c96d8d8..0dee209 100644 --- a/manifest.json +++ b/manifest.json @@ -1,7 +1,7 @@ { "id": "obsidian-excalidraw-plugin", "name": "Excalidraw", - "version": "1.2.24", + "version": "1.3.0", "minAppVersion": "0.12.0", "description": "An Obsidian plugin to edit and view Excalidraw drawings", "author": "Zsolt Viczian", diff --git a/src/ExcalidrawAutomate.ts b/src/ExcalidrawAutomate.ts index 0b0d451..af6524f 100644 --- a/src/ExcalidrawAutomate.ts +++ b/src/ExcalidrawAutomate.ts @@ -48,9 +48,10 @@ export interface ExcalidrawAutomate extends Window { setStrokeSharpness(val:number): void; setFontFamily(val:number): void; setTheme(val:number): void; - addToGroup(objectIds:[]):void; + addToGroup(objectIds:[]):string; toClipboard(templatePath?:string): void; getElements():ExcalidrawElement[]; + getElement(id:string):ExcalidrawElement; create(params?:{filename?: string, foldername?:string, templatePath?:string, onNewPane?: boolean}):Promise; createSVG(templatePath?:string):Promise; createPNG(templatePath?:string):Promise; @@ -59,8 +60,8 @@ export interface ExcalidrawAutomate extends Window { addDiamond(topX:number, topY:number, width:number, height:number):string; addEllipse(topX:number, topY:number, width:number, height:number):string; addText(topX:number, topY:number, text:string, formatting?:{width?:number, height?:number,textAlign?: string, verticalAlign?:string, box?: boolean, boxPadding?: number},id?:string):string; - addLine(points: [[x:number,y:number]]):void; - addArrow(points: [[x:number,y:number]],formatting?:{startArrowHead?:string,endArrowHead?:string,startObjectId?:string,endObjectId?:string}):void ; + addLine(points: [[x:number,y:number]]):string; + addArrow(points: [[x:number,y:number]],formatting?:{startArrowHead?:string,endArrowHead?:string,startObjectId?:string,endObjectId?:string}):string ; connectObjects(objectA: string, connectionA: ConnectionPoint, objectB: string, connectionB: ConnectionPoint, formatting?:{numberOfPoints?: number,startArrowHead?:string,endArrowHead?:string, padding?: number}):void; clear(): void; reset(): void; @@ -68,6 +69,7 @@ export interface ExcalidrawAutomate extends Window { //view manipulation targetView: ExcalidrawView; setView(view:ExcalidrawView|"first"|"active"):ExcalidrawView; + getExcalidrawAPI():any; getViewSelectedElement():ExcalidrawElement; connectObjectWithViewSelectedElement(objectA:string,connectionA: ConnectionPoint, connectionB: ConnectionPoint, formatting?:{numberOfPoints?: number,startArrowHead?:string,endArrowHead?:string, padding?: number}):boolean; addElementsToView(repositionToCursor:boolean, save:boolean):Promise; @@ -158,11 +160,12 @@ export async function initExcalidrawAutomate(plugin: ExcalidrawPlugin) { return "dark"; } }, - addToGroup(objectIds:[]):void { + addToGroup(objectIds:[]):string { const id = nanoid(); objectIds.forEach((objectId)=>{ this.elementsDict[objectId]?.groupIds?.push(id); }); + return id; }, async toClipboard(templatePath?:string) { const template = templatePath ? (await getTemplate(templatePath)) : null; @@ -182,6 +185,9 @@ export async function initExcalidrawAutomate(plugin: ExcalidrawPlugin) { } return elements; }, + getElement(id:string):ExcalidrawElement { + return this.elementsDict[id]; + }, async create(params?:{filename?: string, foldername?:string, templatePath?:string, onNewPane?: boolean}) { const template = params?.templatePath ? (await getTemplate(params.templatePath)) : null; let elements = template ? template.elements : []; @@ -305,7 +311,7 @@ export async function initExcalidrawAutomate(plugin: ExcalidrawPlugin) { } return id; }, - addLine(points: [[x:number,y:number]]):void { + addLine(points: [[x:number,y:number]]):string { const box = getLineBox(points); const id = nanoid(); //this.elementIds.push(id); @@ -318,8 +324,9 @@ export async function initExcalidrawAutomate(plugin: ExcalidrawPlugin) { endArrowhead: null, ... boxedElement(id,"line",box.x,box.y,box.w,box.h) }; + return id; }, - addArrow(points: [[x:number,y:number]],formatting?:{startArrowHead?:string,endArrowHead?:string,startObjectId?:string,endObjectId?:string}):void { + addArrow(points: [[x:number,y:number]],formatting?:{startArrowHead?:string,endArrowHead?:string,startObjectId?:string,endObjectId?:string}):string { const box = getLineBox(points); const id = nanoid(); //this.elementIds.push(id); @@ -340,6 +347,7 @@ export async function initExcalidrawAutomate(plugin: ExcalidrawPlugin) { if(!this.elementsDict[formatting.endObjectId].boundElementIds) this.elementsDict[formatting.endObjectId].boundElementIds = []; this.elementsDict[formatting.endObjectId].boundElementIds.push(id); } + return id; }, connectObjects(objectA: string, connectionA: ConnectionPoint, objectB: string, connectionB: ConnectionPoint, formatting?:{numberOfPoints?: number,startArrowHead?:string,endArrowHead?:string, padding?: number}):void { if(!(this.elementsDict[objectA] && this.elementsDict[objectB])) { @@ -415,6 +423,10 @@ export async function initExcalidrawAutomate(plugin: ExcalidrawPlugin) { if(view instanceof ExcalidrawView) this.targetView = view; return this.targetView; }, + getExcalidrawAPI():any { + if (!this.targetView || !this.targetView?._loaded) return null; + return (this.targetView as ExcalidrawView).excalidrawRef.current; + }, getViewSelectedElement():any { if (!this.targetView || !this.targetView?._loaded) return null; const current = this.targetView?.excalidrawRef?.current; diff --git a/versions.json b/versions.json index 310ab1e..a9d35c9 100644 --- a/versions.json +++ b/versions.json @@ -1,3 +1,3 @@ { - "1.2.24": "0.11.13" + "1.3.0": "0.11.13" }