1.3.0

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<void>;
-  createSVG(templatePath?:string):Promise<SVGSVGElement>;
-  createPNG(templatePath?:string):Promise<any>;
-  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<void>;
+createSVG(templatePath?:string):Promise<SVGSVGElement>;
+createPNG(templatePath?:string):Promise<any>;
+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<boolean>;
 };
-```
+```
+

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`.
+Groups objects listed in `objectIds`. Returns the `id` of the group.

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.
+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<boolean>
+```
+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.