@markerjs/markerjs3 3.0.0-beta.3 → 3.0.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/markerjs3.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Describes point objects used internally
2
+ * Describes a point objects use internally
3
3
  */
4
4
  interface IPoint {
5
5
  /**
@@ -12,6 +12,32 @@ interface IPoint {
12
12
  y: number;
13
13
  }
14
14
 
15
+ /**
16
+ * Describes a size
17
+ */
18
+ interface ISize {
19
+ /**
20
+ * Width
21
+ */
22
+ width: number;
23
+ /**
24
+ * Height
25
+ */
26
+ height: number;
27
+ }
28
+
29
+ /**
30
+ * Represents a simplified version of the SVGMatrix.
31
+ */
32
+ interface ITransformMatrix {
33
+ a: number;
34
+ b: number;
35
+ c: number;
36
+ d: number;
37
+ e: number;
38
+ f: number;
39
+ }
40
+
15
41
  /**
16
42
  * Utility class to simplify SVG operations.
17
43
  */
@@ -132,7 +158,10 @@ declare class SvgHelper {
132
158
  }
133
159
 
134
160
  /**
135
- * Represents marker's state used to save and restore state continue annotation in the future.
161
+ * Represents marker's state used to save and restore state.
162
+ *
163
+ * The state can then be serialized and stored for future use like to continue
164
+ * annotation in the future, display it in a viewer or render as a static image.
136
165
  */
137
166
  interface MarkerBaseState {
138
167
  /**
@@ -143,38 +172,100 @@ interface MarkerBaseState {
143
172
  * Additional information about the marker.
144
173
  */
145
174
  notes?: string;
175
+ /**
176
+ * Marker's stroke (outline) color.
177
+ */
146
178
  strokeColor?: string;
179
+ /**
180
+ * Marker's stroke (outline) width.
181
+ */
147
182
  strokeWidth?: number;
183
+ /**
184
+ * Marker's stroke (outline) dash array.
185
+ */
148
186
  strokeDasharray?: string;
187
+ /**
188
+ * Marker's opacity.
189
+ */
149
190
  opacity?: number;
150
191
  }
151
192
 
193
+ /**
194
+ * Represents the state of the annotation.
195
+ *
196
+ * The state is returned by {@link Editor!MarkerArea.getState | MarkerArea.getState()} and can be used to
197
+ * restore the annotation in {@link Editor!MarkerArea | MarkerArea}
198
+ * with {@link Editor!MarkerArea.restoreState | MarkerArea.restoreState()}
199
+ * or passed to {@link Viewer!MarkerView.show | MakerView.show()}
200
+ * or {@link Renderer!Renderer.rasterize | Renderer.rasterize()}.
201
+ */
152
202
  interface AnnotationState {
203
+ /**
204
+ * Version of the annotation state format.
205
+ *
206
+ * Equals to 3 for the current version.
207
+ */
153
208
  version?: number;
209
+ /**
210
+ * Width of the annotation.
211
+ */
154
212
  width: number;
213
+ /**
214
+ * Height of the annotation.
215
+ */
155
216
  height: number;
217
+ /**
218
+ * Array of marker states for markers in the annotation.
219
+ */
156
220
  markers: MarkerBaseState[];
157
221
  }
158
222
 
159
223
  /**
160
- * Describes a size
224
+ * Represents a stage in a marker's lifecycle.
225
+ *
226
+ * Most markers are created immediately after the user clicks on the canvas.
227
+ * However, some markers are only finished creating after additional interactions.
161
228
  */
162
- interface ISize {
163
- width: number;
164
- height: number;
165
- }
166
-
167
229
  type MarkerStage = 'creating' | 'normal';
230
+ /**
231
+ * Base class for all markers.
232
+ *
233
+ * When creating custom marker types usually you will want to extend one of the derived classes.
234
+ * However, if you cannot find a suitable base class, you can and you should extend this class.
235
+ *
236
+ * @summary Base class for all markers.
237
+ * @group Markers
238
+ */
168
239
  declare class MarkerBase {
240
+ /**
241
+ * Marker type name.
242
+ *
243
+ * It's important to set this in each derived class. This value is used to identify marker types
244
+ * when restoring marker state and other scenarios.
245
+ */
169
246
  static typeName: string;
247
+ /**
248
+ * Returns marker type name for the object instance.
249
+ */
170
250
  get typeName(): string;
251
+ /**
252
+ * SVG container object holding the marker's visual.
253
+ *
254
+ * It is created and passed to the constructor by marker editor or viewer when creating the marker.
255
+ */
171
256
  protected _container: SVGGElement;
257
+ /**
258
+ * SVG container object holding the marker's visual.
259
+ */
172
260
  /**
173
261
  * SVG container object holding the marker's visual.
174
262
  */
175
263
  get container(): SVGGElement;
176
264
  /**
177
- * Additional information about the marker
265
+ * Additional information about the marker.
266
+ *
267
+ * Generally, this isn't used for anything functional.
268
+ * However, in a derived type it could be used for storing arbitrary data with no need to create extra properties and state types.
178
269
  */
179
270
  notes?: string;
180
271
  /**
@@ -185,39 +276,120 @@ declare class MarkerBase {
185
276
  * Marker type title (display name) used for accessibility and other attributes.
186
277
  */
187
278
  static title: string;
279
+ /**
280
+ * Marker lifecycle stage.
281
+ *
282
+ * Most markers are created immediately after the user clicks on the canvas (`normal`).
283
+ * However, some markers are only finished creating after additional interactions (`creating`).
284
+ */
188
285
  stage: MarkerStage;
286
+ /**
287
+ * Stroke (outline) color of the marker.
288
+ */
189
289
  protected _strokeColor: string;
290
+ /**
291
+ * Stroke (outline) color of the marker.
292
+ *
293
+ * In a derived class override {@link applyStrokeColor} to apply the color to the marker's visual.
294
+ */
190
295
  get strokeColor(): string;
191
296
  set strokeColor(color: string);
297
+ /**
298
+ * Applies the stroke color to the marker's visual.
299
+ *
300
+ * Override this method in a derived class to apply the color to the marker's visual.
301
+ */
192
302
  protected applyStrokeColor(): void;
303
+ /**
304
+ * Fill color of the marker.
305
+ */
193
306
  protected _fillColor: string;
307
+ /**
308
+ * Fill color of the marker.
309
+ *
310
+ * In a derived class override {@link applyFillColor} to apply the color to the marker's visual.
311
+ */
194
312
  get fillColor(): string;
195
313
  set fillColor(color: string);
314
+ /**
315
+ * Applies the fill color to the marker's visual.
316
+ *
317
+ * Override this method in a derived class to apply the color to the marker's visual.
318
+ */
196
319
  protected applyFillColor(): void;
320
+ /**
321
+ * Stroke (outline) width of the marker.
322
+ */
197
323
  protected _strokeWidth: number;
324
+ /**
325
+ * Stroke (outline) width of the marker.
326
+ *
327
+ * In a derived class override {@link applyStrokeWidth} to apply the width to the marker's visual.
328
+ */
198
329
  get strokeWidth(): number;
199
330
  set strokeWidth(value: number);
331
+ /**
332
+ * Applies the stroke width to the marker's visual.
333
+ *
334
+ * Override this method in a derived class to apply the width to the marker's visual.
335
+ */
200
336
  protected applyStrokeWidth(): void;
337
+ /**
338
+ * Stroke (outline) dash array of the marker.
339
+ */
201
340
  protected _strokeDasharray: string;
341
+ /**
342
+ * Stroke (outline) dash array of the marker.
343
+ *
344
+ * In a derived class override {@link applyStrokeDasharray} to apply the dash array to the marker's visual.
345
+ */
202
346
  get strokeDasharray(): string;
203
347
  set strokeDasharray(value: string);
348
+ /**
349
+ * Applies the stroke dash array to the marker's visual.
350
+ *
351
+ * Override this method in a derived class to apply the dash array to the marker's visual.
352
+ */
204
353
  protected applyStrokeDasharray(): void;
354
+ /**
355
+ * Opacity of the marker.
356
+ */
205
357
  protected _opacity: number;
358
+ /**
359
+ * Opacity of the marker.
360
+ *
361
+ * In a derived class override {@link applyOpacity} to apply the opacity to the marker's visual.
362
+ */
206
363
  get opacity(): number;
207
364
  set opacity(value: number);
365
+ /**
366
+ * Applies the opacity to the marker's visual.
367
+ *
368
+ * Override this method in a derived class to apply the opacity to the marker's visual
369
+ */
208
370
  protected applyOpacity(): void;
371
+ /**
372
+ * Creates a new marker object.
373
+ *
374
+ * @param container - SVG container object holding the marker's visual.
375
+ */
209
376
  constructor(container: SVGGElement);
210
377
  /**
211
378
  * Returns true if passed SVG element belongs to the marker. False otherwise.
212
379
  *
213
380
  * @param el - target element.
381
+ * @returns true if the element belongs to the marker.
214
382
  */
215
383
  ownsTarget(el: EventTarget): boolean;
216
384
  /**
217
- * Disposes the marker and clean's up.
385
+ * Disposes the marker and cleans up.
218
386
  */
219
387
  dispose(): void;
220
388
  protected addMarkerVisualToContainer(element: SVGElement): void;
389
+ /**
390
+ * When overridden in a derived class, represents a preliminary outline for markers that can be displayed before the marker is actually created.
391
+ * @returns SVG path string.
392
+ */
221
393
  getOutline(): string;
222
394
  /**
223
395
  * Returns current marker state that can be restored in the future.
@@ -230,7 +402,7 @@ declare class MarkerBase {
230
402
  */
231
403
  restoreState(state: MarkerBaseState): void;
232
404
  /**
233
- * Scales marker. Used after the image resize.
405
+ * Scales marker. Used after resize.
234
406
  *
235
407
  * @param scaleX - horizontal scale
236
408
  * @param scaleY - vertical scale
@@ -246,18 +418,6 @@ declare class MarkerBase {
246
418
  getBBox(): DOMRect;
247
419
  }
248
420
 
249
- /**
250
- * Represents a simplified version of the SVGMatrix.
251
- */
252
- interface ITransformMatrix {
253
- a: number;
254
- b: number;
255
- c: number;
256
- d: number;
257
- e: number;
258
- f: number;
259
- }
260
-
261
421
  /**
262
422
  * Represents a state snapshot of a RectangularBoxMarkerBase.
263
423
  */
@@ -282,13 +442,26 @@ interface RectangularBoxMarkerBaseState extends MarkerBaseState {
282
442
  * Marker's rotation angle.
283
443
  */
284
444
  rotationAngle: number;
445
+ /**
446
+ * Visual transform matrix.
447
+ *
448
+ * Used to correctly position and rotate marker.
449
+ */
285
450
  visualTransformMatrix?: ITransformMatrix;
451
+ /**
452
+ * Container transform matrix.
453
+ *
454
+ * Used to correctly position and rotate marker.
455
+ */
286
456
  containerTransformMatrix?: ITransformMatrix;
287
457
  }
288
458
 
289
459
  /**
290
460
  * RectangularBoxMarkerBase is a base class for all marker's that conceptually fit into a rectangle
291
461
  * such as all rectangle markers, ellipse, text and callout markers.
462
+ *
463
+ * @summary Base class for all markers that conceptually fit into a rectangle.
464
+ * @group Markers
292
465
  */
293
466
  declare class RectangularBoxMarkerBase extends MarkerBase {
294
467
  /**
@@ -331,7 +504,14 @@ declare class RectangularBoxMarkerBase extends MarkerBase {
331
504
  * @param point - coordinates of the new top-left corner of the visual.
332
505
  */
333
506
  moveVisual(point: IPoint): void;
507
+ /**
508
+ * Adjusts marker's size.
509
+ */
334
510
  setSize(): void;
511
+ /**
512
+ * Rotates marker around the center.
513
+ * @param point - coordinates of the rotation point.
514
+ */
335
515
  rotate(point: IPoint): void;
336
516
  private applyRotation;
337
517
  /**
@@ -344,30 +524,19 @@ declare class RectangularBoxMarkerBase extends MarkerBase {
344
524
  * @param point - rotated point coordinates.
345
525
  */
346
526
  unrotatePoint(point: IPoint): IPoint;
347
- /**
348
- * Returns marker's outline path for use while creating, etc.
349
- * @returns SVG path `d` attribute.
350
- */
351
527
  getOutline(): string;
352
- /**
353
- * Returns marker's state.
354
- */
355
528
  getState(): RectangularBoxMarkerBaseState;
356
- /**
357
- * Restores marker's state to the previously saved one.
358
- * @param state - previously saved state.
359
- */
360
529
  restoreState(state: MarkerBaseState): void;
361
- /**
362
- * Scales marker. Used after the image resize.
363
- *
364
- * @param scaleX - horizontal scale
365
- * @param scaleY - vertical scale
366
- */
367
530
  scale(scaleX: number, scaleY: number): void;
368
531
  getBBox(): DOMRect;
369
532
  }
370
533
 
534
+ /**
535
+ * Shape outline marker is a base class for all markers that represent a shape outline.
536
+ *
537
+ * @summary Base class for shape outline (unfilled shape) markers.
538
+ * @group Markers
539
+ */
371
540
  declare class ShapeOutlineMarkerBase extends RectangularBoxMarkerBase {
372
541
  static title: string;
373
542
  protected applyStrokeColor(): void;
@@ -378,21 +547,17 @@ declare class ShapeOutlineMarkerBase extends RectangularBoxMarkerBase {
378
547
  ownsTarget(el: EventTarget): boolean;
379
548
  protected getPath(width?: number, height?: number): string;
380
549
  getOutline(): string;
381
- createVisual(): void;
382
- adjustVisual(): void;
383
- setSize(): void;
384
550
  /**
385
- * Restores previously saved marker state.
386
- *
387
- * @param state - previously saved state.
551
+ * Creates marker's visual.
388
552
  */
389
- restoreState(state: MarkerBaseState): void;
553
+ createVisual(): void;
390
554
  /**
391
- * Scales marker. Used after the image resize.
392
- *
393
- * @param scaleX - horizontal scale
394
- * @param scaleY - vertical scale
555
+ * Adjusts marker's visual according to the current state
556
+ * (color, width, etc.).
395
557
  */
558
+ adjustVisual(): void;
559
+ setSize(): void;
560
+ restoreState(state: MarkerBaseState): void;
396
561
  scale(scaleX: number, scaleY: number): void;
397
562
  }
398
563
 
@@ -403,42 +568,50 @@ interface ShapeOutlineMarkerBaseState extends RectangularBoxMarkerBaseState {
403
568
  }
404
569
 
405
570
  /**
406
- * Represents shape's state.
571
+ * Represents filled shape's state.
407
572
  */
408
573
  interface ShapeMarkerBaseState extends ShapeOutlineMarkerBaseState {
574
+ /**
575
+ * Marker's fill color.
576
+ */
409
577
  fillColor: string;
410
578
  }
411
579
 
580
+ /**
581
+ * Base class for filled shape markers.
582
+ *
583
+ * @summary Base class for filled shape markers.
584
+ * @group Markers
585
+ */
412
586
  declare abstract class ShapeMarkerBase extends ShapeOutlineMarkerBase {
413
587
  static title: string;
414
- protected _fillColor: string;
415
- protected applyFillColor(): void;
416
- constructor(container: SVGGElement);
417
- createVisual(): void;
418
588
  /**
419
- * Returns current marker state that can be restored in the future.
589
+ * Marker's fill color.
420
590
  */
421
- getState(): ShapeMarkerBaseState;
591
+ protected _fillColor: string;
422
592
  /**
423
- * Restores previously saved marker state.
593
+ * Applies the fill color to the marker's visual.
424
594
  *
425
- * @param state - previously saved state.
595
+ * If needed, override this method in a derived class to apply the color to the marker's visual.
426
596
  */
597
+ protected applyFillColor(): void;
598
+ constructor(container: SVGGElement);
599
+ createVisual(): void;
600
+ getState(): ShapeMarkerBaseState;
427
601
  restoreState(state: MarkerBaseState): void;
428
602
  }
429
603
 
604
+ /**
605
+ * Frame marker represents unfilled rectangle shape.
606
+ *
607
+ * @summary Unfilled rectangle marker.
608
+ * @group Markers
609
+ */
430
610
  declare class FrameMarker extends ShapeOutlineMarkerBase {
431
- /**
432
- * String type name of the marker type.
433
- */
434
611
  static typeName: string;
435
- /**
436
- * Marker type title (display name) used for accessibility and other attributes.
437
- */
438
612
  static title: string;
439
613
  constructor(container: SVGGElement);
440
614
  protected getPath(width?: number, height?: number): string;
441
- getState(): ShapeOutlineMarkerBaseState;
442
615
  }
443
616
 
444
617
  /**
@@ -463,6 +636,14 @@ interface LinearMarkerBaseState extends MarkerBaseState {
463
636
  y2: number;
464
637
  }
465
638
 
639
+ /**
640
+ * Base class for line-like markers.
641
+ *
642
+ * Use one of the derived classes.
643
+ *
644
+ * @summary Base class for line-like markers.
645
+ * @group Markers
646
+ */
466
647
  declare class LinearMarkerBase extends MarkerBase {
467
648
  /**
468
649
  * x coordinate of the first end-point
@@ -484,91 +665,111 @@ declare class LinearMarkerBase extends MarkerBase {
484
665
  * Marker's main visual.
485
666
  */
486
667
  protected visual: SVGGraphicsElement | undefined;
668
+ /**
669
+ * Wider invisible visual to make it easier to select and manipulate the marker.
670
+ */
487
671
  protected selectorVisual: SVGGraphicsElement | undefined;
672
+ /**
673
+ * Visible visual of the marker.
674
+ */
488
675
  protected visibleVisual: SVGGraphicsElement | undefined;
489
676
  protected applyStrokeColor(): void;
490
677
  protected applyStrokeWidth(): void;
491
678
  protected applyStrokeDasharray(): void;
492
679
  protected applyOpacity(): void;
493
680
  constructor(container: SVGGElement);
681
+ ownsTarget(el: EventTarget): boolean;
494
682
  /**
495
- * Returns true if passed SVG element belongs to the marker. False otherwise.
683
+ * The path representing the marker visual.
496
684
  *
497
- * @param el - target element.
685
+ * When implemented in derived class should return SVG path for the marker.
686
+ *
687
+ * @returns SVG path for the marker.
498
688
  */
499
- ownsTarget(el: EventTarget): boolean;
500
689
  protected getPath(): string;
501
- createVisual(): void;
502
690
  /**
503
- * When implemented adjusts marker visual after manipulation when needed.
691
+ * Creates marker's visual.
504
692
  */
505
- adjustVisual(): void;
693
+ createVisual(): void;
506
694
  /**
507
- * Returns marker's state.
695
+ * Adjusts marker visual after manipulation when needed.
508
696
  */
697
+ adjustVisual(): void;
509
698
  getState(): LinearMarkerBaseState;
510
- /**
511
- * Restores marker's state to the previously saved one.
512
- * @param state - previously saved state.
513
- */
514
699
  restoreState(state: MarkerBaseState): void;
515
- /**
516
- * Scales marker. Used after the image resize.
517
- *
518
- * @param scaleX - horizontal scale
519
- * @param scaleY - vertical scale
520
- */
521
700
  scale(scaleX: number, scaleY: number): void;
522
701
  }
523
702
 
703
+ /**
704
+ * Line marker represents a simple straight line.
705
+ *
706
+ * @summary Line marker.
707
+ * @group Markers
708
+ */
524
709
  declare class LineMarker extends LinearMarkerBase {
525
710
  static typeName: string;
526
711
  static title: string;
527
712
  constructor(container: SVGGElement);
528
713
  protected getPath(): string;
529
- /**
530
- * Returns current marker state that can be restored in the future.
531
- */
532
- getState(): LinearMarkerBaseState;
533
714
  }
534
715
 
716
+ /**
717
+ * Arrow type.
718
+ *
719
+ * Specifies whether the arrow should be drawn at the start, end, both ends or none.
720
+ */
535
721
  type ArrowType = 'both' | 'start' | 'end' | 'none';
722
+ /**
723
+ * Represents the state of the arrow marker.
724
+ */
536
725
  interface ArrowMarkerState extends LinearMarkerBaseState {
537
726
  arrowType: ArrowType;
538
727
  }
539
728
 
729
+ /**
730
+ * Arrow marker represents a line with arrow heads at the ends.
731
+ *
732
+ * @summary A line with arrow heads at the ends.
733
+ *
734
+ * @group Markers
735
+ */
540
736
  declare class ArrowMarker extends LineMarker {
541
737
  static typeName: string;
542
738
  static title: string;
543
739
  private _arrowType;
740
+ /**
741
+ * Type of the arrow.
742
+ *
743
+ * Specify whether the arrow should be drawn at the start, end, both ends or none.
744
+ */
544
745
  get arrowType(): ArrowType;
545
746
  set arrowType(value: ArrowType);
546
747
  constructor(container: SVGGElement);
547
748
  protected getPath(): string;
548
749
  protected applyStrokeWidth(): void;
549
- /**
550
- * Returns marker's state.
551
- */
552
750
  getState(): ArrowMarkerState;
553
- /**
554
- * Restores marker's state to the previously saved one.
555
- * @param state - previously saved state.
556
- */
557
751
  restoreState(state: MarkerBaseState): void;
558
752
  }
559
753
 
754
+ /**
755
+ * Represents a measurement marker.
756
+ *
757
+ * Measurement marker is a line with two vertical bars at the ends.
758
+ *
759
+ * @summary A line with two vertical bars at the ends.
760
+ * @group Markers
761
+ */
560
762
  declare class MeasurementMarker extends LineMarker {
561
763
  static typeName: string;
562
764
  static title: string;
563
765
  constructor(container: SVGGElement);
564
766
  protected getPath(): string;
565
767
  protected applyStrokeWidth(): void;
566
- /**
567
- * Returns marker's state.
568
- */
569
- getState(): LinearMarkerBaseState;
570
768
  }
571
769
 
770
+ /**
771
+ * Represents polygon marker's state used to save and restore state.
772
+ */
572
773
  interface PolygonMarkerState extends MarkerBaseState {
573
774
  /**
574
775
  * Polygon points.
@@ -576,9 +777,18 @@ interface PolygonMarkerState extends MarkerBaseState {
576
777
  points: Array<IPoint>;
577
778
  }
578
779
 
780
+ /**
781
+ * Polygon marker is a multi-point marker that represents a polygon.
782
+ *
783
+ * @summary Polygon marker.
784
+ * @group Markers
785
+ */
579
786
  declare class PolygonMarker extends MarkerBase {
580
787
  static typeName: string;
581
788
  static title: string;
789
+ /**
790
+ * Marker's points.
791
+ */
582
792
  points: IPoint[];
583
793
  /**
584
794
  * Marker's main visual.
@@ -592,85 +802,95 @@ declare class PolygonMarker extends MarkerBase {
592
802
  protected applyStrokeDasharray(): void;
593
803
  protected applyOpacity(): void;
594
804
  constructor(container: SVGGElement);
805
+ ownsTarget(el: EventTarget): boolean;
595
806
  /**
596
- * Returns true if passed SVG element belongs to the marker. False otherwise.
807
+ * Returns SVG path string for the polygon.
597
808
  *
598
- * @param el - target element.
809
+ * @returns Path string for the polygon.
599
810
  */
600
- ownsTarget(el: EventTarget): boolean;
601
811
  protected getPath(): string;
812
+ /**
813
+ * Creates marker's main visual.
814
+ */
602
815
  createVisual(): void;
816
+ /**
817
+ * Creates selector visual.
818
+ *
819
+ * Selector visual is a transparent wider visual that allows easier selection of the marker.
820
+ */
603
821
  private createSelectorVisual;
604
822
  /**
605
- * When implemented adjusts marker visual after manipulation when needed.
823
+ * Adjusts marker visual after manipulation when needed.
606
824
  */
607
825
  adjustVisual(): void;
608
826
  private adjustSelectorVisual;
609
827
  private addSelectorLine;
610
- /**
611
- * Returns marker's state.
612
- */
613
828
  getState(): PolygonMarkerState;
614
- /**
615
- * Restores marker's state to the previously saved one.
616
- * @param state - previously saved state.
617
- */
618
829
  restoreState(state: MarkerBaseState): void;
619
- /**
620
- * Scales marker. Used after the image resize.
621
- *
622
- * @param scaleX - horizontal scale
623
- * @param scaleY - vertical scale
624
- */
625
830
  scale(scaleX: number, scaleY: number): void;
626
831
  }
627
832
 
833
+ /**
834
+ * Represents the state of a freehand marker.
835
+ */
628
836
  interface FreehandMarkerState extends MarkerBaseState {
837
+ /**
838
+ * Points of the freehand line.
839
+ */
629
840
  points: Array<IPoint>;
630
841
  }
631
842
 
843
+ /**
844
+ * Freehand marker represents a hand drawing.
845
+ *
846
+ * Unlike v2 in v3 freehand marker is represented by an SVG path element.
847
+ * This means that the line properties like stroke color, width, dasharray, etc.
848
+ * can be modified after drawing.
849
+ *
850
+ * @summary Freehand drawing marker.
851
+ * @group Markers
852
+ */
632
853
  declare class FreehandMarker extends MarkerBase {
633
854
  static typeName: string;
634
855
  static title: string;
856
+ /**
857
+ * Points of the freehand line.
858
+ */
635
859
  points: IPoint[];
636
860
  /**
637
861
  * Marker's main visual.
638
862
  */
639
863
  visual: SVGGraphicsElement | undefined;
864
+ /**
865
+ * Wider invisible visual to make it easier to select and manipulate the marker.
866
+ */
640
867
  protected selectorVisual: SVGGraphicsElement | undefined;
868
+ /**
869
+ * Visible visual of the marker.
870
+ */
641
871
  visibleVisual: SVGGraphicsElement | undefined;
642
872
  protected applyStrokeColor(): void;
643
873
  protected applyStrokeWidth(): void;
644
874
  protected applyStrokeDasharray(): void;
645
875
  protected applyOpacity(): void;
646
876
  constructor(container: SVGGElement);
877
+ ownsTarget(el: EventTarget): boolean;
647
878
  /**
648
- * Returns true if passed SVG element belongs to the marker. False otherwise.
879
+ * Returns SVG path string representing the freehand line.
649
880
  *
650
- * @param el - target element.
881
+ * @returns SVG path string representing the freehand line.
651
882
  */
652
- ownsTarget(el: EventTarget): boolean;
653
883
  protected getPath(): string;
654
- createVisual(): void;
655
884
  /**
656
- * When implemented adjusts marker visual after manipulation when needed.
885
+ * Creates the visual elements comprising the marker's visual.
657
886
  */
658
- adjustVisual(): void;
887
+ createVisual(): void;
659
888
  /**
660
- * Returns marker's state.
889
+ * Adjusts marker visual after manipulation or with new points.
661
890
  */
891
+ adjustVisual(): void;
662
892
  getState(): FreehandMarkerState;
663
- /**
664
- * Restores marker's state to the previously saved one.
665
- * @param state - previously saved state.
666
- */
667
893
  restoreState(state: MarkerBaseState): void;
668
- /**
669
- * Scales marker. Used after the image resize.
670
- *
671
- * @param scaleX - horizontal scale
672
- * @param scaleY - vertical scale
673
- */
674
894
  scale(scaleX: number, scaleY: number): void;
675
895
  }
676
896
 
@@ -693,7 +913,7 @@ interface FontSize {
693
913
  }
694
914
 
695
915
  /**
696
- * TextBlock represents a block of text used across all text-based stencils and connector labels.
916
+ * TextBlock represents a block of text used across all text-based markers.
697
917
  */
698
918
  declare class TextBlock {
699
919
  /**
@@ -704,7 +924,7 @@ declare class TextBlock {
704
924
  onTextSizeChanged?: (textBlock: TextBlock) => void;
705
925
  private _text;
706
926
  /**
707
- * Returns the text block's text
927
+ * Returns the text block's text.
708
928
  */
709
929
  get text(): string;
710
930
  /**
@@ -813,57 +1033,86 @@ declare class TextBlock {
813
1033
  hideControlBox(): void;
814
1034
  }
815
1035
 
1036
+ /**
1037
+ * Represents a state snapshot of a TextMarker.
1038
+ */
816
1039
  interface TextMarkerState extends RectangularBoxMarkerBaseState {
1040
+ /**
1041
+ * Text color.
1042
+ */
817
1043
  color: string;
1044
+ /**
1045
+ * Font family.
1046
+ */
818
1047
  fontFamily: string;
1048
+ /**
1049
+ * Font size.
1050
+ */
819
1051
  fontSize: FontSize;
1052
+ /**
1053
+ * Text content.
1054
+ */
820
1055
  text: string;
821
1056
  }
822
1057
 
1058
+ /**
1059
+ * Text marker.
1060
+ *
1061
+ * Used to represent a text block as well a base class for other text-based markers.
1062
+ *
1063
+ * @summary Text marker.
1064
+ * @group Markers
1065
+ */
823
1066
  declare class TextMarker extends RectangularBoxMarkerBase {
824
1067
  static typeName: string;
825
1068
  static title: string;
1069
+ /**
1070
+ * Default text for the marker type.
1071
+ */
826
1072
  protected static DEFAULT_TEXT: string;
1073
+ /**
1074
+ * Callback to be called when the text size changes.
1075
+ */
827
1076
  onSizeChanged?: (textMarker: TextMarker) => void;
828
1077
  private _color;
829
1078
  /**
830
- * Returns stencil's text color.
1079
+ * Returns markers's text color.
831
1080
  */
832
1081
  get color(): string;
833
1082
  /**
834
- * Sets the stencil's text color.
1083
+ * Sets the markers's text color.
835
1084
  */
836
1085
  set color(value: string);
837
1086
  private _fontFamily;
838
1087
  /**
839
- * Returns the stencil's font family.
1088
+ * Returns the markers's font family.
840
1089
  */
841
1090
  get fontFamily(): string;
842
1091
  /**
843
- * Sets the stencil's font family.
1092
+ * Sets the markers's font family.
844
1093
  */
845
1094
  set fontFamily(value: string);
846
1095
  private _fontSize;
847
1096
  /**
848
- * Returns the stencil's font size.
1097
+ * Returns the marker's font size.
849
1098
  */
850
1099
  get fontSize(): FontSize;
851
1100
  /**
852
- * Sets the stencil's font size.
1101
+ * Sets the marker's font size.
853
1102
  */
854
1103
  set fontSize(value: FontSize);
855
1104
  /**
856
- * Returns the default text for the stencil type.
857
- * @returns stencil type's default text.
1105
+ * Returns the default text for the marker type.
1106
+ * @returns marker type's default text.
858
1107
  */
859
1108
  protected getDefaultText(): string;
860
1109
  private _text;
861
1110
  /**
862
- * Returns the stencil's text.
1111
+ * Returns the marker's text.
863
1112
  */
864
1113
  get text(): string;
865
1114
  /**
866
- * Sets the stencil's text.
1115
+ * Sets the marker's text.
867
1116
  */
868
1117
  set text(value: string);
869
1118
  /**
@@ -879,14 +1128,26 @@ declare class TextMarker extends RectangularBoxMarkerBase {
879
1128
  */
880
1129
  textBlock: TextBlock;
881
1130
  constructor(container: SVGGElement);
1131
+ /**
1132
+ * Creates marker's visual.
1133
+ */
882
1134
  createVisual(): void;
1135
+ /**
1136
+ * Adjusts marker's visual according to the current state.
1137
+ */
883
1138
  adjustVisual(): void;
884
1139
  ownsTarget(el: EventTarget): boolean;
1140
+ /**
1141
+ * Sets the text bounding box.
1142
+ */
885
1143
  protected setTextBoundingBox(): void;
886
1144
  /**
887
- * Sets (adjusts) the stencil's size.
1145
+ * Sets (adjusts) the marker's size.
888
1146
  */
889
1147
  setSize(): void;
1148
+ /**
1149
+ * Sets the marker's size based on the text size.
1150
+ */
890
1151
  protected setSizeFromTextSize(): void;
891
1152
  private textSizeChanged;
892
1153
  /**
@@ -904,54 +1165,77 @@ declare class TextMarker extends RectangularBoxMarkerBase {
904
1165
  * @param fontSize font size
905
1166
  */
906
1167
  setFontSize(fontSize: FontSize): void;
1168
+ /**
1169
+ * Hides the marker's visual.
1170
+ *
1171
+ * Used when editing the text.
1172
+ */
907
1173
  hideVisual(): void;
908
- showVisual(): void;
909
- getState(): TextMarkerState;
910
1174
  /**
911
- * Restores previously saved marker state.
1175
+ * Shows the marker's visual.
912
1176
  *
913
- * @param state - previously saved state.
1177
+ * Eg. when done editing the text.
914
1178
  */
1179
+ showVisual(): void;
1180
+ getState(): TextMarkerState;
915
1181
  restoreState(state: MarkerBaseState): void;
916
1182
  scale(scaleX: number, scaleY: number): void;
917
1183
  }
918
1184
 
1185
+ /**
1186
+ * Cover marker is a filled rectangle marker.
1187
+ *
1188
+ * A typical use case is to cover some area of the image with a colored rectangle as a "redaction".
1189
+ *
1190
+ * @summary Filled rectangle marker.
1191
+ * @group Markers
1192
+ */
919
1193
  declare class CoverMarker extends ShapeMarkerBase {
920
- /**
921
- * String type name of the marker type.
922
- */
923
1194
  static typeName: string;
924
- /**
925
- * Marker type title (display name) used for accessibility and other attributes.
926
- */
927
1195
  static title: string;
928
1196
  constructor(container: SVGGElement);
929
1197
  protected getPath(width?: number, height?: number): string;
930
- getState(): ShapeMarkerBaseState;
931
1198
  }
932
1199
 
1200
+ /**
1201
+ * Highlight marker is a semi-transparent rectangular marker.
1202
+ *
1203
+ * @summary Semi-transparent rectangular marker.
1204
+ * @group Markers
1205
+ */
933
1206
  declare class HighlightMarker extends ShapeMarkerBase {
934
- /**
935
- * String type name of the marker type.
936
- */
937
1207
  static typeName: string;
938
- /**
939
- * Marker type title (display name) used for accessibility and other attributes.
940
- */
941
1208
  static title: string;
942
1209
  constructor(container: SVGGElement);
943
1210
  protected getPath(width?: number, height?: number): string;
944
- getState(): ShapeMarkerBaseState;
945
1211
  }
946
1212
 
1213
+ /**
1214
+ * Represents the state of a callout marker.
1215
+ */
947
1216
  interface CalloutMarkerState extends TextMarkerState {
1217
+ /**
1218
+ * Coordinates of the position of the tip of the callout.
1219
+ */
948
1220
  tipPosition: IPoint;
949
1221
  }
950
1222
 
1223
+ /**
1224
+ * Callout marker is a text-based marker with a callout outline with a tip that can point to specific place
1225
+ * on the underlying image or annotation.
1226
+ *
1227
+ * @summary Text-based marker with a callout outline with a tip that can point to specific place
1228
+ * on the underlying image or annotation.
1229
+ *
1230
+ * @group Markers
1231
+ */
951
1232
  declare class CalloutMarker extends TextMarker {
952
1233
  static typeName: string;
953
1234
  static title: string;
954
1235
  private _tipPosition;
1236
+ /**
1237
+ * Coordinates of the position of the tip of the callout.
1238
+ */
955
1239
  get tipPosition(): IPoint;
956
1240
  set tipPosition(value: IPoint);
957
1241
  private tipBase1Position;
@@ -963,6 +1247,11 @@ declare class CalloutMarker extends TextMarker {
963
1247
  protected applyStrokeDasharray(): void;
964
1248
  protected applyOpacity(): void;
965
1249
  protected applyFillColor(): void;
1250
+ /**
1251
+ * Returns the SVG path string for the callout outline.
1252
+ *
1253
+ * @returns Path string for the callout outline.
1254
+ */
966
1255
  protected getPath(): string;
967
1256
  private setTipPoints;
968
1257
  createVisual(): void;
@@ -973,55 +1262,98 @@ declare class CalloutMarker extends TextMarker {
973
1262
  scale(scaleX: number, scaleY: number): void;
974
1263
  }
975
1264
 
1265
+ /**
1266
+ * Ellipse frame marker represents unfilled circle/ellipse shape.
1267
+ *
1268
+ * @summary Unfilled ellipse marker.
1269
+ * @group Markers
1270
+ */
976
1271
  declare class EllipseFrameMarker extends ShapeOutlineMarkerBase {
977
- /**
978
- * String type name of the marker type.
979
- */
980
1272
  static typeName: string;
981
- /**
982
- * Marker type title (display name) used for accessibility and other attributes.
983
- */
984
1273
  static title: string;
985
1274
  constructor(container: SVGGElement);
986
1275
  protected getPath(width?: number, height?: number): string;
987
- getState(): ShapeOutlineMarkerBaseState;
988
1276
  }
989
1277
 
1278
+ /**
1279
+ * Ellipse marker is a filled ellipse marker.
1280
+ *
1281
+ * @summary Filled ellipse marker.
1282
+ * @group Markers
1283
+ */
990
1284
  declare class EllipseMarker extends ShapeMarkerBase {
991
- /**
992
- * String type name of the marker type.
993
- */
994
1285
  static typeName: string;
995
- /**
996
- * Marker type title (display name) used for accessibility and other attributes.
997
- */
998
1286
  static title: string;
999
1287
  constructor(container: SVGGElement);
1000
1288
  protected getPath(width?: number, height?: number): string;
1001
- getState(): ShapeMarkerBaseState;
1002
1289
  }
1003
1290
 
1291
+ /**
1292
+ * The type of image (svg or bitmap).
1293
+ *
1294
+ * Used in {@link Core!ImageMarkerBase | ImageMarkerBase } and its descendants.
1295
+ */
1004
1296
  type ImageType = 'svg' | 'bitmap';
1005
1297
  /**
1006
1298
  * Represents image marker's state.
1007
1299
  */
1008
1300
  interface ImageMarkerBaseState extends RectangularBoxMarkerBaseState {
1301
+ /**
1302
+ * Type of the image: SVG or bitmap.
1303
+ */
1009
1304
  imageType?: ImageType;
1305
+ /**
1306
+ * SVG markup of the SVG image.
1307
+ */
1010
1308
  svgString?: string;
1309
+ /**
1310
+ * Image source (URL or base64 encoded image).
1311
+ */
1011
1312
  imageSrc?: string;
1012
1313
  }
1013
1314
 
1315
+ /**
1316
+ * Base class for image markers.
1317
+ *
1318
+ * This class isn't meant to be used directly. Use one of the derived classes instead.
1319
+ *
1320
+ * @summary Image marker base class.
1321
+ * @group Markers
1322
+ */
1014
1323
  declare class ImageMarkerBase extends RectangularBoxMarkerBase {
1015
1324
  static title: string;
1016
1325
  /**
1017
- * Main SVG or image element of the stencil.
1326
+ * Main SVG or image element of the marker.
1018
1327
  */
1019
1328
  protected SVGImage?: SVGSVGElement | SVGImageElement;
1329
+ /**
1330
+ * Type of the image: SVG or bitmap.
1331
+ */
1020
1332
  protected imageType: ImageType;
1333
+ /**
1334
+ * For SVG images this holds the SVG markup of the image.
1335
+ */
1021
1336
  protected _svgString?: string;
1337
+ /**
1338
+ * For SVG images this holds the SVG markup of the image.
1339
+ */
1022
1340
  get svgString(): string | undefined;
1023
1341
  set svgString(value: string | undefined);
1342
+ /**
1343
+ * For bitmap images this holds the base64 encoded image.
1344
+ */
1024
1345
  protected _imageSrc?: string;
1346
+ /**
1347
+ * For bitmap images this holds the base64 encoded image.
1348
+ *
1349
+ * @remarks
1350
+ * Technically this could be any URL but due to browser security constraints
1351
+ * an external image will almost certainly cause bitmap rendering of the image to fail.
1352
+ *
1353
+ * In cases you know you will never render the annotation as a static image,
1354
+ * it should be safe to use external URLs. Otherwise, use base64 encoded images
1355
+ * like 'data:image/png;base64,...'.
1356
+ */
1025
1357
  get imageSrc(): string | undefined;
1026
1358
  set imageSrc(value: string | undefined);
1027
1359
  /**
@@ -1033,8 +1365,17 @@ declare class ImageMarkerBase extends RectangularBoxMarkerBase {
1033
1365
  */
1034
1366
  protected naturalHeight: number;
1035
1367
  constructor(container: SVGGElement);
1368
+ /**
1369
+ * Creates the image element based on the image type and source.
1370
+ */
1036
1371
  protected createImage(): void;
1372
+ /**
1373
+ * Creates marker's visual, including its image element.
1374
+ */
1037
1375
  createVisual(): void;
1376
+ /**
1377
+ * Adjusts the image size and position.
1378
+ */
1038
1379
  adjustImage(): void;
1039
1380
  private isDescendant;
1040
1381
  ownsTarget(el: EventTarget): boolean;
@@ -1042,62 +1383,63 @@ declare class ImageMarkerBase extends RectangularBoxMarkerBase {
1042
1383
  getState(): ImageMarkerBaseState;
1043
1384
  protected applyStrokeColor(): void;
1044
1385
  restoreState(state: ImageMarkerBaseState): void;
1045
- /**
1046
- * Scales marker. Used after the image resize.
1047
- *
1048
- * @param scaleX - horizontal scale
1049
- * @param scaleY - vertical scale
1050
- */
1051
1386
  scale(scaleX: number, scaleY: number): void;
1052
1387
  }
1053
1388
 
1054
1389
  /**
1055
1390
  * Used to represent user-set images.
1391
+ *
1392
+ * Use this marker to display custom images at runtime.
1393
+ * For example, you can use this type to represent emojis selected in an emoji picker.
1394
+ *
1395
+ * @summary Custom image marker.
1396
+ * @group Markers
1056
1397
  */
1057
1398
  declare class CustomImageMarker extends ImageMarkerBase {
1058
- /**
1059
- * String type name of the marker type.
1060
- */
1061
1399
  static typeName: string;
1062
- /**
1063
- * Marker type title (display name) used for accessibility and other attributes.
1064
- */
1065
1400
  static title: string;
1066
1401
  }
1067
1402
 
1068
1403
  /**
1069
1404
  * Check mark marker.
1405
+ *
1406
+ * Represents a check mark image marker. Can be used to quickly mark something as correct, or
1407
+ * similar use cases.
1408
+ *
1409
+ * @summary Check mark image marker.
1410
+ * @group Markers
1070
1411
  */
1071
1412
  declare class CheckImageMarker extends ImageMarkerBase {
1072
- /**
1073
- * String type name of the marker type.
1074
- */
1075
1413
  static typeName: string;
1076
- /**
1077
- * Marker type title (display name) used for accessibility and other attributes.
1078
- */
1079
1414
  static title: string;
1080
1415
  constructor(container: SVGGElement);
1081
1416
  }
1082
1417
 
1083
1418
  /**
1084
- * X mark marker.
1419
+ * X mark image marker.
1420
+ *
1421
+ * @summary X (crossed) image marker.
1422
+ * @group Markers
1085
1423
  */
1086
1424
  declare class XImageMarker extends ImageMarkerBase {
1087
- /**
1088
- * String type name of the marker type.
1089
- */
1090
1425
  static typeName: string;
1091
- /**
1092
- * Marker type title (display name) used for accessibility and other attributes.
1093
- */
1094
1426
  static title: string;
1095
1427
  constructor(container: SVGGElement);
1096
1428
  }
1097
1429
 
1430
+ /**
1431
+ * Represents the state of a caption frame marker.
1432
+ */
1098
1433
  interface CaptionFrameMarkerState extends TextMarkerState, ShapeMarkerBaseState {
1099
1434
  }
1100
1435
 
1436
+ /**
1437
+ * Caption frame marker is a combination of a frame (rectangle) and a text caption that goes with it.
1438
+ *
1439
+ * @summary A combination of a frame (rectangle) and a text caption that goes with it.
1440
+ *
1441
+ * @group Markers
1442
+ */
1101
1443
  declare class CaptionFrameMarker extends TextMarker {
1102
1444
  static typeName: string;
1103
1445
  static title: string;
@@ -1110,30 +1452,50 @@ declare class CaptionFrameMarker extends TextMarker {
1110
1452
  protected applyStrokeDasharray(): void;
1111
1453
  protected applyOpacity(): void;
1112
1454
  protected applyFillColor(): void;
1455
+ /**
1456
+ * Returns the SVG path strings for the frame and the caption background.
1457
+ *
1458
+ * @param width
1459
+ * @param height
1460
+ * @returns SVG path strings for the frame and the caption background.
1461
+ */
1113
1462
  protected getPaths(width?: number, height?: number): {
1114
1463
  frame: string;
1115
1464
  caption: string;
1116
1465
  };
1117
1466
  createVisual(): void;
1118
1467
  adjustVisual(): void;
1468
+ /**
1469
+ * Adjusts text position inside the caption frame.
1470
+ */
1119
1471
  protected adjustTextPosition(): void;
1472
+ /**
1473
+ * Adjusts frame visual according to the current marker properties.
1474
+ */
1120
1475
  protected adjustFrameVisual(): void;
1121
1476
  ownsTarget(el: EventTarget): boolean;
1122
1477
  setSize(): void;
1123
1478
  protected setSizeFromTextSize(): void;
1479
+ /**
1480
+ * Hides the marker visual.
1481
+ *
1482
+ * Used by the editor to hide rendered marker while editing the text.
1483
+ */
1124
1484
  hideVisual(): void;
1125
- showVisual(): void;
1126
- getState(): CaptionFrameMarkerState;
1127
- restoreState(state: MarkerBaseState): void;
1128
1485
  /**
1129
- * Scales marker. Used after the image resize.
1486
+ * Shows the marker visual.
1130
1487
  *
1131
- * @param scaleX - horizontal scale
1132
- * @param scaleY - vertical scale
1488
+ * Used by the editor to show rendered marker after editing the text.
1133
1489
  */
1490
+ showVisual(): void;
1491
+ getState(): CaptionFrameMarkerState;
1492
+ restoreState(state: MarkerBaseState): void;
1134
1493
  scale(scaleX: number, scaleY: number): void;
1135
1494
  }
1136
1495
 
1496
+ /**
1497
+ * Properties for marker editor.
1498
+ */
1137
1499
  interface MarkerEditorProperties<TMarkerType extends MarkerBase = MarkerBase> {
1138
1500
  /**
1139
1501
  * SVG container for the marker and editor elements.
@@ -1157,19 +1519,56 @@ interface MarkerEditorProperties<TMarkerType extends MarkerBase = MarkerBase> {
1157
1519
  * Represents marker's state (status) in time.
1158
1520
  */
1159
1521
  type MarkerEditorState = 'new' | 'creating' | 'select' | 'move' | 'resize' | 'rotate' | 'edit';
1522
+ /**
1523
+ * Marker creation style defines whether markers are created by drawing them or just dropping them on the canvas.
1524
+ */
1160
1525
  type MarkerCreationStyle = 'draw' | 'drop';
1526
+ /**
1527
+ * Base class for all marker editors.
1528
+ *
1529
+ * @typeParam TMarkerType - marker type the instance of the editor is for.
1530
+ *
1531
+ * @summary Base class for all marker editors.
1532
+ * @group Editors
1533
+ */
1161
1534
  declare class MarkerBaseEditor<TMarkerType extends MarkerBase = MarkerBase> {
1535
+ /**
1536
+ * Marker type constructor.
1537
+ */
1162
1538
  protected _markerType: new (container: SVGGElement) => TMarkerType;
1539
+ /**
1540
+ * Marker creation style.
1541
+ *
1542
+ * Markers can either be created by drawing them or just dropping them on the canvas.
1543
+ */
1163
1544
  protected _creationStyle: MarkerCreationStyle;
1545
+ /**
1546
+ * Marker creation style.
1547
+ *
1548
+ * Markers can either be created by drawing them or just dropping them on the canvas.
1549
+ */
1164
1550
  get creationStyle(): MarkerCreationStyle;
1165
1551
  /**
1166
1552
  * Type guard for specific marker editor types.
1553
+ *
1554
+ * This allows to check if the editor is of a specific type which is useful for displaying type-specific UI.
1555
+ *
1556
+ * @typeParam T - specific marker editor type.
1167
1557
  * @param cls
1168
1558
  * @returns
1169
1559
  */
1170
1560
  is<T>(cls: new (...args: any[]) => T): this is T;
1561
+ /**
1562
+ * Marker instance.
1563
+ */
1171
1564
  protected _marker: TMarkerType;
1565
+ /**
1566
+ * Returns the marker instance.
1567
+ */
1172
1568
  get marker(): TMarkerType;
1569
+ /**
1570
+ * SVG container for the marker's and editor's visual elements.
1571
+ */
1173
1572
  protected _container: SVGGElement;
1174
1573
  /**
1175
1574
  * Returns the SVG container for the marker's and editor's visual elements.
@@ -1219,32 +1618,73 @@ declare class MarkerBaseEditor<TMarkerType extends MarkerBase = MarkerBase> {
1219
1618
  * Returns true if the marker is currently selected
1220
1619
  */
1221
1620
  get isSelected(): boolean;
1621
+ /**
1622
+ * When set to true, a new marker of the same type is created immediately after the current one is finished.
1623
+ */
1222
1624
  protected _continuousCreation: boolean;
1625
+ /**
1626
+ * When set to true, a new marker of the same type is created immediately after the current one is finished.
1627
+ */
1223
1628
  get continuousCreation(): boolean;
1224
1629
  /**
1225
- * Sets rectangle's border stroke color.
1630
+ * Sets marker's stroke (outline) color.
1226
1631
  * @param color - color as string
1227
1632
  */
1228
1633
  set strokeColor(color: string);
1634
+ /**
1635
+ * Gets marker's stroke (outline) color.
1636
+ */
1229
1637
  get strokeColor(): string;
1230
1638
  /**
1231
- * Sets rectangle's border stroke (line) width.
1232
- * @param color - color as string
1639
+ * Sets marker's stroke (outline) width.
1640
+ * @param width - stroke width in pixels.
1233
1641
  */
1234
1642
  set strokeWidth(width: number);
1643
+ /**
1644
+ * Gets marker's stroke (outline) width.
1645
+ */
1235
1646
  get strokeWidth(): number;
1236
1647
  /**
1237
- * Sets rectangle's border stroke dash array.
1238
- * @param color - color as string
1648
+ * Sets marker's stroke (outline) dash array.
1649
+ * @param dashes - dash array as string
1239
1650
  */
1240
1651
  set strokeDasharray(dashes: string);
1652
+ /**
1653
+ * Gets marker's stroke (outline) dash array.
1654
+ */
1241
1655
  get strokeDasharray(): string;
1656
+ /**
1657
+ * Sets marker's fill color.
1658
+ */
1242
1659
  set fillColor(color: string);
1660
+ /**
1661
+ * Gets marker's fill color.
1662
+ */
1243
1663
  get fillColor(): string;
1664
+ /**
1665
+ * Sets marker's opacity.
1666
+ */
1244
1667
  set opacity(value: number);
1668
+ /**
1669
+ * Gets marker's opacity.
1670
+ */
1245
1671
  get opacity(): number;
1672
+ /**
1673
+ * Creates a new instance of marker editor.
1674
+ *
1675
+ * @param properties - marker editor properties.
1676
+ */
1246
1677
  constructor(properties: MarkerEditorProperties<TMarkerType>);
1678
+ /**
1679
+ * Returns true if the marker or the editor owns supplied target element.
1680
+ *
1681
+ * @param el target element
1682
+ * @returns
1683
+ */
1247
1684
  ownsTarget(el: EventTarget | null): boolean;
1685
+ /**
1686
+ * Is this marker selected in a multi-selection?
1687
+ */
1248
1688
  protected isMultiSelected: boolean;
1249
1689
  /**
1250
1690
  * Selects this marker and displays appropriate selected marker UI.
@@ -1284,13 +1724,27 @@ declare class MarkerBaseEditor<TMarkerType extends MarkerBase = MarkerBase> {
1284
1724
  * Disposes the marker and clean's up.
1285
1725
  */
1286
1726
  dispose(): void;
1727
+ /**
1728
+ * Adjusts marker's control box.
1729
+ */
1287
1730
  protected adjustControlBox(): void;
1731
+ /**
1732
+ * Scales the marker and the editor.
1733
+ *
1734
+ * @param scaleX
1735
+ * @param scaleY
1736
+ */
1288
1737
  scale(scaleX: number, scaleY: number): void;
1289
1738
  /**
1290
1739
  * Called by a marker when its state could have changed.
1291
1740
  * Does a check if the state has indeed changed before firing the handler.
1292
1741
  */
1293
1742
  protected stateChanged(): void;
1743
+ /**
1744
+ * Returns marker's state that can be restored in the future.
1745
+ *
1746
+ * @returns
1747
+ */
1294
1748
  getState(): MarkerBaseState;
1295
1749
  /**
1296
1750
  * Restores previously saved marker state.
@@ -1300,33 +1754,129 @@ declare class MarkerBaseEditor<TMarkerType extends MarkerBase = MarkerBase> {
1300
1754
  restoreState(state: MarkerBaseState): void;
1301
1755
  }
1302
1756
 
1757
+ /**
1758
+ * Marker area custom event types.
1759
+ */
1303
1760
  interface MarkerAreaEventMap {
1304
1761
  /**
1305
1762
  * Marker area initialized.
1306
1763
  */
1307
1764
  areainit: CustomEvent<MarkerAreaEventData>;
1765
+ /**
1766
+ * Marker area shown.
1767
+ */
1308
1768
  areashow: CustomEvent<MarkerAreaEventData>;
1769
+ /**
1770
+ * Marker area state restored.
1771
+ */
1309
1772
  arearestorestate: CustomEvent<MarkerAreaEventData>;
1773
+ /**
1774
+ * Marker area focused.
1775
+ */
1310
1776
  areafocus: CustomEvent<MarkerAreaEventData>;
1777
+ /**
1778
+ * Marker area lost focus.
1779
+ */
1311
1780
  areablur: CustomEvent<MarkerAreaEventData>;
1781
+ /**
1782
+ * Marker area state changed.
1783
+ */
1312
1784
  areastatechange: CustomEvent<MarkerAreaEventData>;
1785
+ /**
1786
+ * Marker selected.
1787
+ */
1313
1788
  markerselect: CustomEvent<MarkerEditorEventData>;
1789
+ /**
1790
+ * Marker deselected.
1791
+ */
1314
1792
  markerdeselect: CustomEvent<MarkerEditorEventData>;
1793
+ /**
1794
+ * Marker creating.
1795
+ */
1315
1796
  markercreating: CustomEvent<MarkerEditorEventData>;
1797
+ /**
1798
+ * Marker created.
1799
+ */
1316
1800
  markercreate: CustomEvent<MarkerEditorEventData>;
1801
+ /**
1802
+ * Marker about to be deleted.
1803
+ */
1317
1804
  markerbeforedelete: CustomEvent<MarkerEditorEventData>;
1805
+ /**
1806
+ * Marker deleted.
1807
+ */
1318
1808
  markerdelete: CustomEvent<MarkerEditorEventData>;
1809
+ /**
1810
+ * Marker changed.
1811
+ */
1319
1812
  markerchange: CustomEvent<MarkerEditorEventData>;
1320
1813
  }
1814
+ /**
1815
+ * Marker area custom event data.
1816
+ */
1321
1817
  interface MarkerAreaEventData {
1322
1818
  /**
1323
1819
  * {@link MarkerArea} instance.
1324
1820
  */
1325
1821
  markerArea: MarkerArea;
1326
1822
  }
1823
+ /**
1824
+ * Marker editor custom event data.
1825
+ */
1327
1826
  interface MarkerEditorEventData extends MarkerAreaEventData {
1328
1827
  markerEditor: MarkerBaseEditor;
1329
1828
  }
1829
+ /**
1830
+ * @ignore
1831
+ */
1832
+ type MarkerAreaMode = 'select' | 'create' | 'delete';
1833
+ /**
1834
+ * Marker area web component is the main annotation editor component.
1835
+ *
1836
+ * @summary
1837
+ * The main annotation editor component.
1838
+ *
1839
+ * @group Components
1840
+ *
1841
+ * @example
1842
+ *
1843
+ * Import `MarkerArea` from `@markerjs/markerjs3`:
1844
+ *
1845
+ * ```js
1846
+ * import { MarkerArea } from '@markerjs/markerjs3';
1847
+ * ```
1848
+ *
1849
+ * In the code below we assume that you have an `HTMLImageElement` as `targetImage`. It can be a reference to an image you already have on the page or you can simply create it with something like this:
1850
+ *
1851
+ * ```js
1852
+ * const targetImg = document.createElement('img');
1853
+ * targetImg.src = './sample.jpg';
1854
+ * ```
1855
+ *
1856
+ * Now you just need to create an instance of `MarkerArea`, set its `targetImage` property and add it to the page:
1857
+ *
1858
+ * ```js
1859
+ * const markerArea = new MarkerArea();
1860
+ * markerArea.targetImage = targetImg;
1861
+ * editorContainerDiv.appendChild(markerArea);
1862
+ * ```
1863
+ *
1864
+ * To initiate creation of a marker you just call `createMarker()` and pass it the name (or type) of the marker you want to create. So, if you have a button with id `addFrameButton` you can make it create a new `FrameMarker` with something like this:
1865
+ *
1866
+ * ```js
1867
+ * document.querySelector("#addButton")!.addEventListener("click", () => {
1868
+ * markerArea.createMarker("FrameMarker");
1869
+ * });
1870
+ * ```
1871
+ *
1872
+ * And whenever you want to save state (current annotation) you just call `getState()`:
1873
+ *
1874
+ * ```js
1875
+ * document.querySelector("#saveStateButton")!.addEventListener("click", () => {
1876
+ * const state = markerArea.getState();
1877
+ * console.log(state);
1878
+ * });
1879
+ */
1330
1880
  declare class MarkerArea extends HTMLElement {
1331
1881
  private _contentContainer?;
1332
1882
  private _canvasContainer?;
@@ -1338,22 +1888,50 @@ declare class MarkerArea extends HTMLElement {
1338
1888
  private width;
1339
1889
  private height;
1340
1890
  private _targetWidth;
1891
+ /**
1892
+ * Returns the target image width.
1893
+ */
1341
1894
  get targetWidth(): number;
1895
+ /**
1896
+ * Sets the target image width.
1897
+ */
1342
1898
  set targetWidth(value: number);
1343
1899
  private _targetHeight;
1900
+ /**
1901
+ * Returns the target image height.
1902
+ */
1344
1903
  get targetHeight(): number;
1904
+ /**
1905
+ * Sets the target image height.
1906
+ */
1345
1907
  set targetHeight(value: number);
1346
1908
  private mode;
1347
1909
  private _logoUI?;
1348
1910
  private _isInitialized;
1349
1911
  private _currentMarkerEditor?;
1912
+ /**
1913
+ * Returns the currently active marker editor.
1914
+ */
1350
1915
  get currentMarkerEditor(): MarkerBaseEditor | undefined;
1351
1916
  private _selectedMarkerEditors;
1352
1917
  private _newMarkerOutline;
1918
+ private _targetImageLoaded;
1353
1919
  private _targetImage;
1920
+ /**
1921
+ * Returns the target image.
1922
+ */
1354
1923
  get targetImage(): HTMLImageElement | undefined;
1924
+ /**
1925
+ * Sets the target image.
1926
+ */
1355
1927
  set targetImage(value: HTMLImageElement | undefined);
1928
+ /**
1929
+ * The collection of available marker editor types.
1930
+ */
1356
1931
  markerEditors: Map<typeof MarkerBase, typeof MarkerBaseEditor<MarkerBase>>;
1932
+ /**
1933
+ * The collection of marker editors in the annotation.
1934
+ */
1357
1935
  editors: MarkerBaseEditor[];
1358
1936
  private _zoomLevel;
1359
1937
  /**
@@ -1376,15 +1954,47 @@ declare class MarkerArea extends HTMLElement {
1376
1954
  private setEditingTargetSize;
1377
1955
  private initOverlay;
1378
1956
  private addTargetImage;
1957
+ /**
1958
+ * Registers a marker type and its editor to be available in the marker area.
1959
+ * @param markerType
1960
+ * @param editorType
1961
+ */
1379
1962
  registerMarkerType(markerType: typeof MarkerBase, editorType: typeof MarkerBaseEditor<MarkerBase>): void;
1963
+ /**
1964
+ * Creates a new marker of the specified type.
1965
+ * @param markerType
1966
+ * @returns
1967
+ */
1380
1968
  createMarker(markerType: typeof MarkerBase | string): MarkerBaseEditor<MarkerBase> | undefined;
1381
1969
  private addNewMarker;
1382
1970
  private markerCreated;
1383
1971
  private markerStateChanged;
1972
+ /**
1973
+ * Deletes a marker represented by the specified editor.
1974
+ * @param markerEditor
1975
+ */
1384
1976
  deleteMarker(markerEditor: MarkerBaseEditor): void;
1977
+ /**
1978
+ * Deselects all markers.
1979
+ */
1385
1980
  deleteSelectedMarkers(): void;
1981
+ /**
1982
+ * Sets the current editor and selects it.
1983
+ *
1984
+ * If `editor` is not supplied the current editor is unselected.
1985
+ *
1986
+ * @param editor
1987
+ */
1386
1988
  setCurrentEditor(editor?: MarkerBaseEditor): void;
1989
+ /**
1990
+ * Selects the specified editor without setting it as the current editor.
1991
+ * @param editor
1992
+ */
1387
1993
  selectEditor(editor: MarkerBaseEditor): void;
1994
+ /**
1995
+ * Deselects the specified editor (or all editors if not specified).
1996
+ * @param editor
1997
+ */
1388
1998
  deselectEditor(editor?: MarkerBaseEditor): void;
1389
1999
  private touchPoints;
1390
2000
  private isDragging;
@@ -1410,8 +2020,20 @@ declare class MarkerArea extends HTMLElement {
1410
2020
  private detachEvents;
1411
2021
  private detachWindowEvents;
1412
2022
  private getMarkerTypeByName;
2023
+ /**
2024
+ * Switches the marker area to select mode and deselects all the selected markers.
2025
+ */
1413
2026
  switchToSelectMode(): void;
2027
+ /**
2028
+ * Returns the annotation state.
2029
+ * @returns
2030
+ */
1414
2031
  getState(): AnnotationState;
2032
+ private _stateToRestore;
2033
+ /**
2034
+ * Restores the annotation from the previously saved state.
2035
+ * @param state
2036
+ */
1415
2037
  restoreState(state: AnnotationState): void;
1416
2038
  private scaleMarkers;
1417
2039
  /**
@@ -1452,10 +2074,8 @@ declare class MarkerArea extends HTMLElement {
1452
2074
  }
1453
2075
 
1454
2076
  /**
1455
- * Color type marks the kind of color property a color is referring to.
2077
+ * Represents location of the manipulation grips.
1456
2078
  */
1457
- type ColorType = 'text' | 'stroke' | 'fill' | 'background';
1458
-
1459
2079
  type GripLocation = 'topleft' | 'topcenter' | 'topright' | 'leftcenter' | 'rightcenter' | 'bottomleft' | 'bottomcenter' | 'bottomright';
1460
2080
  /**
1461
2081
  * Represents a single resize-manipulation grip used in marker's manipulation controls.
@@ -1465,17 +2085,29 @@ declare class Grip {
1465
2085
  * Grip's visual element.
1466
2086
  */
1467
2087
  protected _visual?: SVGGraphicsElement;
2088
+ /**
2089
+ * Grip's visual element.
2090
+ */
1468
2091
  get visual(): SVGGraphicsElement;
1469
2092
  /**
1470
2093
  * Grip's size (radius).
1471
2094
  */
1472
2095
  gripSize: number;
2096
+ /**
2097
+ * Grip's fill color.
2098
+ */
1473
2099
  fillColor: string;
2100
+ /**
2101
+ * Grip's stroke color.
2102
+ */
1474
2103
  strokeColor: string;
1475
2104
  /**
1476
2105
  * Creates a new grip.
1477
2106
  */
1478
2107
  constructor();
2108
+ /**
2109
+ * Creates grip's visual.
2110
+ */
1479
2111
  protected createVisual(): void;
1480
2112
  /**
1481
2113
  * Returns true if passed SVG element belongs to the grip. False otherwise.
@@ -1485,13 +2117,25 @@ declare class Grip {
1485
2117
  ownsTarget(el: EventTarget): boolean;
1486
2118
  }
1487
2119
 
2120
+ /**
2121
+ * Represents a resize grip.
2122
+ */
1488
2123
  declare class ResizeGrip extends Grip {
1489
2124
  }
1490
2125
 
2126
+ /**
2127
+ * Represents a rotation grip.
2128
+ */
1491
2129
  declare class RotateGrip extends Grip {
1492
2130
  constructor();
1493
2131
  }
1494
2132
 
2133
+ /**
2134
+ * Base editor for markers that can be represented by a rectangular area.
2135
+ *
2136
+ * @summary Base editor for markers that can be represented by a rectangular area.
2137
+ * @group Editors
2138
+ */
1495
2139
  declare class RectangularBoxMarkerBaseEditor<TMarkerType extends RectangularBoxMarkerBase = RectangularBoxMarkerBase> extends MarkerBaseEditor<TMarkerType> {
1496
2140
  /**
1497
2141
  * x coordinate of the top-left corner at the start of manipulation.
@@ -1529,65 +2173,65 @@ declare class RectangularBoxMarkerBaseEditor<TMarkerType extends RectangularBoxM
1529
2173
  * Container for the marker's editing controls.
1530
2174
  */
1531
2175
  protected controlBox: SVGGElement;
2176
+ /**
2177
+ * Container for the marker's manipulation grips.
2178
+ */
1532
2179
  protected manipulationBox: SVGGElement;
1533
2180
  private readonly CB_DISTANCE;
1534
2181
  private controlRect?;
1535
2182
  private rotatorGripLine?;
1536
2183
  private controlGrips;
2184
+ /**
2185
+ * Array of disabled resize grips.
2186
+ *
2187
+ * Use this in derived classes to disable specific resize grips.
2188
+ */
1537
2189
  protected disabledResizeGrips: GripLocation[];
1538
2190
  private rotatorGrip?;
2191
+ /**
2192
+ * Active grip during manipulation
2193
+ */
1539
2194
  protected activeGrip?: Grip;
1540
2195
  private disableRotation;
1541
2196
  constructor(properties: MarkerEditorProperties<TMarkerType>);
1542
- /**
1543
- * Returns true if passed SVG element belongs to the marker. False otherwise.
1544
- *
1545
- * @param el - target element.
1546
- */
1547
2197
  ownsTarget(el: EventTarget): boolean;
1548
- /**
1549
- * Handles pointer (mouse, touch, stylus, etc.) down event.
1550
- *
1551
- * @param point - event coordinates.
1552
- * @param target - direct event target element.
1553
- */
1554
2198
  pointerDown(point: IPoint, target?: EventTarget): void;
1555
- protected _suppressMarkerCreateEvent: boolean;
1556
2199
  /**
1557
- * Handles pointer (mouse, touch, stylus, etc.) up event.
1558
- *
1559
- * @param point - event coordinates.
1560
- * @param target - direct event target element.
2200
+ * When set to true marker created event will not be triggered.
1561
2201
  */
2202
+ protected _suppressMarkerCreateEvent: boolean;
1562
2203
  pointerUp(point: IPoint): void;
1563
- /**
1564
- * Handles marker manipulation (move, resize, rotate, etc.).
1565
- *
1566
- * @param point - event coordinates.
1567
- */
1568
2204
  manipulate(point: IPoint): void;
1569
- /**
1570
- * Resizes the marker based on pointer coordinates and context.
1571
- * @param point - pointer coordinates.
1572
- */
1573
2205
  protected resize(point: IPoint): void;
1574
2206
  /**
1575
2207
  * Sets control box size and location.
1576
2208
  */
1577
2209
  protected setSize(): void;
2210
+ select(multi?: boolean): void;
2211
+ deselect(): void;
1578
2212
  /**
1579
- * Displays marker's controls.
2213
+ * Creates control box for manipulation controls.
1580
2214
  */
1581
- select(multi?: boolean): void;
2215
+ protected setupControlBox(): void;
1582
2216
  /**
1583
- * Hides marker's controls.
2217
+ * Adjusts control box size and location.
1584
2218
  */
1585
- deselect(): void;
1586
- private setupControlBox;
1587
2219
  protected adjustControlBox(): void;
2220
+ /**
2221
+ * Adds control grips to control box.
2222
+ */
1588
2223
  protected addControlGrips(): void;
1589
2224
  private createRotateGrip;
2225
+ /**
2226
+ * Updates manipulation grip layout.
2227
+ */
1590
2228
  protected positionGrips(): void;
2229
+ /**
2230
+ * Positions specific grip.
2231
+ * @param grip
2232
+ * @param x
2233
+ * @param y
2234
+ */
1591
2235
  protected positionGrip(grip: SVGGraphicsElement | undefined, x: number, y: number): void;
1592
2236
  /**
1593
2237
  * Hides marker's editing controls.
@@ -1597,51 +2241,53 @@ declare class RectangularBoxMarkerBaseEditor<TMarkerType extends RectangularBoxM
1597
2241
  * Shows marker's editing controls.
1598
2242
  */
1599
2243
  protected showControlBox(): void;
1600
- protected adjustGripVisibility(): void;
1601
2244
  /**
1602
- * Scales marker. Used after the image resize.
1603
- *
1604
- * @param scaleX - horizontal scale
1605
- * @param scaleY - vertical scale
2245
+ * Adjusts visibility of resize grips.
1606
2246
  */
2247
+ protected adjustGripVisibility(): void;
1607
2248
  scale(scaleX: number, scaleY: number): void;
1608
2249
  }
1609
2250
 
2251
+ /**
2252
+ * Editor for shape outline markers.
2253
+ *
2254
+ * @summary Shape outline (unfilled shape) marker editor.
2255
+ * @group Editors
2256
+ */
1610
2257
  declare class ShapeOutlineMarkerEditor<TMarkerType extends ShapeOutlineMarkerBase = ShapeOutlineMarkerBase> extends RectangularBoxMarkerBaseEditor<TMarkerType> {
1611
2258
  constructor(properties: MarkerEditorProperties<TMarkerType>);
1612
- /**
1613
- * Handles pointer (mouse, touch, stylus, etc.) down event.
1614
- *
1615
- * @param point - event coordinates.
1616
- * @param target - direct event target element.
1617
- */
1618
2259
  pointerDown(point: IPoint, target?: EventTarget): void;
1619
- /**
1620
- * Resizes the marker based on the pointer coordinates.
1621
- * @param point - current pointer coordinates.
1622
- */
1623
2260
  protected resize(point: IPoint): void;
1624
- /**
1625
- * Handles pointer (mouse, touch, stylus, etc.) up event.
1626
- *
1627
- * @param point - event coordinates.
1628
- * @param target - direct event target element.
1629
- */
1630
2261
  pointerUp(point: IPoint): void;
1631
2262
  }
1632
2263
 
2264
+ /**
2265
+ * Editor for filled shape markers.
2266
+ *
2267
+ * @summary Filled shape marker editor.
2268
+ * @group Editors
2269
+ */
1633
2270
  declare class ShapeMarkerEditor<TMarkerType extends ShapeMarkerBase = ShapeMarkerBase> extends ShapeOutlineMarkerEditor<TMarkerType> {
1634
2271
  }
1635
2272
 
2273
+ /**
2274
+ * Editor for linear markers.
2275
+ *
2276
+ * @summary Editor for line-like markers.
2277
+ * @group Editors
2278
+ */
1636
2279
  declare class LinearMarkerEditor<TMarkerType extends LinearMarkerBase = LinearMarkerBase> extends MarkerBaseEditor<TMarkerType> {
1637
2280
  /**
1638
2281
  * Default line length when marker is created with a simple click (without dragging).
1639
2282
  */
1640
2283
  protected defaultLength: number;
1641
2284
  /**
1642
- * Pointer coordinates at the start of move or resize.
2285
+ * Pointer X coordinate at the start of move or resize.
1643
2286
  */
1644
2287
  protected manipulationStartX: number;
2288
+ /**
2289
+ * Pointer Y coordinate at the start of move or resize.
2290
+ */
1645
2291
  protected manipulationStartY: number;
1646
2292
  private manipulationStartX1;
1647
2293
  private manipulationStartY1;
@@ -1651,6 +2297,9 @@ declare class LinearMarkerEditor<TMarkerType extends LinearMarkerBase = LinearMa
1651
2297
  * Container for control elements.
1652
2298
  */
1653
2299
  protected controlBox: SVGGElement;
2300
+ /**
2301
+ * Container for manipulation grips.
2302
+ */
1654
2303
  protected manipulationBox: SVGGElement;
1655
2304
  /**
1656
2305
  * First manipulation grip
@@ -1665,36 +2314,10 @@ declare class LinearMarkerEditor<TMarkerType extends LinearMarkerBase = LinearMa
1665
2314
  */
1666
2315
  protected activeGrip?: ResizeGrip;
1667
2316
  constructor(properties: MarkerEditorProperties<TMarkerType>);
1668
- /**
1669
- * Returns true if passed SVG element belongs to the marker. False otherwise.
1670
- *
1671
- * @param el - target element.
1672
- */
1673
2317
  ownsTarget(el: EventTarget): boolean;
1674
- /**
1675
- * Handles pointer (mouse, touch, stylus, etc.) down event.
1676
- *
1677
- * @param point - event coordinates.
1678
- * @param target - direct event target element.
1679
- */
1680
2318
  pointerDown(point: IPoint, target?: EventTarget): void;
1681
- /**
1682
- * Handles pointer (mouse, touch, stylus, etc.) up event.
1683
- *
1684
- * @param point - event coordinates.
1685
- * @param target - direct event target element.
1686
- */
1687
2319
  pointerUp(point: IPoint): void;
1688
- /**
1689
- * Handles marker manipulation (move, resize, rotate, etc.).
1690
- *
1691
- * @param point - event coordinates.
1692
- */
1693
2320
  manipulate(point: IPoint): void;
1694
- /**
1695
- * Resizes the line marker.
1696
- * @param point - current manipulation coordinates.
1697
- */
1698
2321
  protected resize(point: IPoint): void;
1699
2322
  /**
1700
2323
  * Creates control box for manipulation controls.
@@ -1721,70 +2344,53 @@ declare class LinearMarkerEditor<TMarkerType extends LinearMarkerBase = LinearMa
1721
2344
  * @param y - new Y coordinate
1722
2345
  */
1723
2346
  protected positionGrip(grip: SVGGraphicsElement, x: number, y: number): void;
1724
- /**
1725
- * Displays marker's controls.
1726
- */
1727
2347
  select(multi?: boolean): void;
1728
- /**
1729
- * Hides marker's controls.
1730
- */
1731
2348
  deselect(): void;
1732
2349
  }
1733
2350
 
2351
+ /**
2352
+ * Editor for polygon markers.
2353
+ *
2354
+ * @summary Polygon marker editor.
2355
+ * @group Editors
2356
+ */
1734
2357
  declare class PolygonMarkerEditor<TMarkerType extends PolygonMarker = PolygonMarker> extends MarkerBaseEditor<TMarkerType> {
1735
2358
  /**
1736
2359
  * Default line length when marker is created with a simple click (without dragging).
1737
2360
  */
1738
2361
  protected defaultLength: number;
1739
2362
  /**
1740
- * Pointer coordinates at the start of move or resize.
2363
+ * Pointer X coordinate at the start of move or resize.
1741
2364
  */
1742
2365
  protected manipulationStartX: number;
2366
+ /**
2367
+ * Pointer Y coordinate at the start of move or resize.
2368
+ */
1743
2369
  protected manipulationStartY: number;
1744
2370
  /**
1745
2371
  * Container for control elements.
1746
2372
  */
1747
2373
  protected controlBox: SVGGElement;
2374
+ /**
2375
+ * Container for manipulation grips.
2376
+ */
1748
2377
  protected manipulationBox: SVGGElement;
2378
+ /**
2379
+ * Array of manipulation grips.
2380
+ */
1749
2381
  protected grips: ResizeGrip[];
1750
2382
  /**
1751
2383
  * Active manipulation grip.
1752
2384
  */
1753
2385
  protected activeGrip?: ResizeGrip;
1754
2386
  constructor(properties: MarkerEditorProperties<TMarkerType>);
1755
- /**
1756
- * Returns true if passed SVG element belongs to the marker. False otherwise.
1757
- *
1758
- * @param el - target element.
1759
- */
1760
2387
  ownsTarget(el: EventTarget): boolean;
1761
- /**
1762
- * Handles pointer (mouse, touch, stylus, etc.) down event.
1763
- *
1764
- * @param point - event coordinates.
1765
- * @param target - direct event target element.
1766
- */
1767
2388
  pointerDown(point: IPoint, target?: EventTarget): void;
1768
2389
  private startCreation;
1769
2390
  private addNewPointWhileCreating;
1770
2391
  private finishCreation;
1771
- /**
1772
- * Handles pointer (mouse, touch, stylus, etc.) up event.
1773
- *
1774
- * @param point - event coordinates.
1775
- * @param target - direct event target element.
1776
- */
1777
2392
  pointerUp(point: IPoint): void;
1778
- /**
1779
- * Handles marker manipulation (move, resize, rotate, etc.).
1780
- *
1781
- * @param point - event coordinates.
1782
- */
1783
2393
  manipulate(point: IPoint): void;
1784
- /**
1785
- * Resizes the line marker.
1786
- * @param point - current manipulation coordinates.
1787
- */
1788
2394
  protected resize(point: IPoint): void;
1789
2395
  dblClick(point: IPoint, target?: EventTarget | undefined): void;
1790
2396
  /**
@@ -1812,21 +2418,24 @@ declare class PolygonMarkerEditor<TMarkerType extends PolygonMarker = PolygonMar
1812
2418
  * @param y - new Y coordinate
1813
2419
  */
1814
2420
  protected positionGrip(grip: SVGGraphicsElement, x: number, y: number): void;
1815
- /**
1816
- * Displays marker's controls.
1817
- */
1818
2421
  select(multi?: boolean): void;
1819
- /**
1820
- * Hides marker's controls.
1821
- */
1822
2422
  deselect(): void;
1823
2423
  }
1824
2424
 
2425
+ /**
2426
+ * Editor for freehand markers.
2427
+ *
2428
+ * @summary Freehand marker editor.
2429
+ * @group Editors
2430
+ */
1825
2431
  declare class FreehandMarkerEditor<TMarkerType extends FreehandMarker = FreehandMarker> extends MarkerBaseEditor<TMarkerType> {
1826
2432
  /**
1827
- * Pointer coordinates at the start of move or resize.
2433
+ * Pointer X coordinate at the start of move or resize.
1828
2434
  */
1829
2435
  protected manipulationStartX: number;
2436
+ /**
2437
+ * Pointer Y coordinate at the start of move or resize.
2438
+ */
1830
2439
  protected manipulationStartY: number;
1831
2440
  /**
1832
2441
  * Container for control elements.
@@ -1834,47 +2443,19 @@ declare class FreehandMarkerEditor<TMarkerType extends FreehandMarker = Freehand
1834
2443
  protected controlBox: SVGGElement;
1835
2444
  private controlRect?;
1836
2445
  constructor(properties: MarkerEditorProperties<TMarkerType>);
1837
- /**
1838
- * Returns true if passed SVG element belongs to the marker. False otherwise.
1839
- *
1840
- * @param el - target element.
1841
- */
1842
2446
  ownsTarget(el: EventTarget): boolean;
1843
- /**
1844
- * Handles pointer (mouse, touch, stylus, etc.) down event.
1845
- *
1846
- * @param point - event coordinates.
1847
- * @param target - direct event target element.
1848
- */
1849
2447
  pointerDown(point: IPoint, target?: EventTarget): void;
1850
2448
  private startCreation;
1851
2449
  private addNewPointWhileCreating;
1852
2450
  private finishCreation;
1853
- /**
1854
- * Handles pointer (mouse, touch, stylus, etc.) up event.
1855
- *
1856
- * @param point - event coordinates.
1857
- * @param target - direct event target element.
1858
- */
1859
2451
  pointerUp(point: IPoint): void;
1860
- /**
1861
- * Handles marker manipulation (move, resize, rotate, etc.).
1862
- *
1863
- * @param point - event coordinates.
1864
- */
1865
2452
  manipulate(point: IPoint): void;
1866
2453
  /**
1867
2454
  * Creates control box for manipulation controls.
1868
2455
  */
1869
2456
  protected setupControlBox(): void;
1870
2457
  protected adjustControlBox(): void;
1871
- /**
1872
- * Displays marker's controls.
1873
- */
1874
2458
  select(): void;
1875
- /**
1876
- * Hides marker's controls.
1877
- */
1878
2459
  deselect(): void;
1879
2460
  }
1880
2461
 
@@ -1882,6 +2463,9 @@ declare class FreehandMarkerEditor<TMarkerType extends FreehandMarker = Freehand
1882
2463
  * Text changed event handler type.
1883
2464
  */
1884
2465
  type TextChangedHandler = (text: string) => void;
2466
+ /**
2467
+ * Blur event handler type.
2468
+ */
1885
2469
  type BlurHandler = () => void;
1886
2470
  /**
1887
2471
  * Represents a text block editor element.
@@ -1962,12 +2546,21 @@ declare class TextBlockEditor {
1962
2546
  */
1963
2547
  set textColor(value: string);
1964
2548
  private _bgColor;
2549
+ /**
2550
+ * Returns text block's background color.
2551
+ */
1965
2552
  get bgColor(): string;
2553
+ /**
2554
+ * Sets text block's background color.
2555
+ */
1966
2556
  set bgColor(value: string);
1967
2557
  /**
1968
2558
  * Text changed event handler.
1969
2559
  */
1970
2560
  onTextChanged?: TextChangedHandler;
2561
+ /**
2562
+ * Blur event handler.
2563
+ */
1971
2564
  onBlur?: BlurHandler;
1972
2565
  /**
1973
2566
  * Creates a new text block editor instance.
@@ -1990,49 +2583,81 @@ declare class TextBlockEditor {
1990
2583
  blur(): void;
1991
2584
  }
1992
2585
 
2586
+ /**
2587
+ * Editor for text markers.
2588
+ *
2589
+ * @summary Text marker editor.
2590
+ * @group Editors
2591
+ */
1993
2592
  declare class TextMarkerEditor<TMarkerType extends TextMarker = TextMarker> extends RectangularBoxMarkerBaseEditor<TMarkerType> {
2593
+ /**
2594
+ * Container for text block editor.
2595
+ */
1994
2596
  protected textBlockEditorContainer: SVGForeignObjectElement;
2597
+ /**
2598
+ * Text block editor.
2599
+ */
1995
2600
  protected textBlockEditor: TextBlockEditor;
2601
+ /**
2602
+ * Text color.
2603
+ */
1996
2604
  set color(color: string);
2605
+ /**
2606
+ * Text color.
2607
+ */
1997
2608
  get color(): string;
2609
+ /**
2610
+ * Sets text's font family.
2611
+ */
1998
2612
  set fontFamily(font: string);
2613
+ /**
2614
+ * Returns text's font family.
2615
+ */
1999
2616
  get fontFamily(): string;
2617
+ /**
2618
+ * Sets text's font size.
2619
+ */
2000
2620
  set fontSize(size: FontSize);
2621
+ /**
2622
+ * Returns text's font size.
2623
+ */
2001
2624
  get fontSize(): FontSize;
2002
2625
  constructor(properties: MarkerEditorProperties<TMarkerType>);
2003
2626
  private _pointerDownTime;
2004
2627
  private _pointerDownPoint;
2005
- /**
2006
- * Handles pointer (mouse, touch, stylus, etc.) down event.
2007
- *
2008
- * @param point - event coordinates.
2009
- * @param target - direct event target element.
2010
- */
2011
2628
  pointerDown(point: IPoint, target?: EventTarget): void;
2012
2629
  dblClick(point: IPoint, target?: EventTarget): void;
2013
2630
  protected setSize(): void;
2014
- /**
2015
- * Resizes the marker based on the pointer coordinates.
2016
- * @param point - current pointer coordinates.
2017
- */
2018
2631
  protected resize(point: IPoint): void;
2019
- /**
2020
- * Handles pointer (mouse, touch, stylus, etc.) up event.
2021
- *
2022
- * @param point - event coordinates.
2023
- * @param target - direct event target element.
2024
- */
2025
2632
  pointerUp(point: IPoint): void;
2026
2633
  private showEditor;
2027
2634
  private hideEditor;
2028
2635
  private markerSizeChanged;
2029
2636
  }
2030
2637
 
2638
+ /**
2639
+ * Editor for arrow markers.
2640
+ *
2641
+ * @summary Arrow marker editor.
2642
+ * @group Editors
2643
+ */
2031
2644
  declare class ArrowMarkerEditor<TMarkerType extends ArrowMarker = ArrowMarker> extends LinearMarkerEditor<TMarkerType> {
2645
+ /**
2646
+ * Sets the arrow type.
2647
+ */
2032
2648
  set arrowType(value: ArrowType);
2649
+ /**
2650
+ * Returns the arrow type.
2651
+ */
2033
2652
  get arrowType(): ArrowType;
2034
2653
  }
2035
2654
 
2655
+ /**
2656
+ * Editor for callout markers.
2657
+ *
2658
+ * @summary Callout marker editor.
2659
+ * @group Editors
2660
+ */
2036
2661
  declare class CalloutMarkerEditor<TMarkerType extends CalloutMarker = CalloutMarker> extends TextMarkerEditor<TMarkerType> {
2037
2662
  private tipGrip?;
2038
2663
  private manipulationStartTipPositionX;
@@ -2046,43 +2671,75 @@ declare class CalloutMarkerEditor<TMarkerType extends CalloutMarker = CalloutMar
2046
2671
  protected resize(point: IPoint): void;
2047
2672
  }
2048
2673
 
2674
+ /**
2675
+ * Editor for image markers.
2676
+ *
2677
+ * @summary Image marker editor.
2678
+ * @group Editors
2679
+ */
2049
2680
  declare class ImageMarkerEditor<TMarkerType extends ImageMarkerBase = ImageMarkerBase> extends RectangularBoxMarkerBaseEditor<TMarkerType> {
2050
2681
  constructor(properties: MarkerEditorProperties<TMarkerType>);
2051
- /**
2052
- * Handles pointer (mouse, touch, stylus, etc.) down event.
2053
- *
2054
- * @param point - event coordinates.
2055
- * @param target - direct event target element.
2056
- */
2057
2682
  pointerDown(point: IPoint, target?: EventTarget): void;
2058
- /**
2059
- * Handles pointer (mouse, touch, stylus, etc.) up event.
2060
- *
2061
- * @param point - event coordinates.
2062
- * @param target - direct event target element.
2063
- */
2064
2683
  pointerUp(point: IPoint): void;
2065
2684
  }
2066
2685
 
2686
+ /**
2687
+ * Editor for caption frame markers.
2688
+ *
2689
+ * @summary Caption frame marker editor.
2690
+ * @group Editors
2691
+ */
2067
2692
  declare class CaptionFrameMarkerEditor<TMarkerType extends CaptionFrameMarker = CaptionFrameMarker> extends TextMarkerEditor<TMarkerType> {
2068
2693
  constructor(properties: MarkerEditorProperties<TMarkerType>);
2069
2694
  protected setSize(): void;
2070
2695
  }
2071
2696
 
2697
+ /**
2698
+ * Event map for {@link MarkerView}.
2699
+ */
2072
2700
  interface MarkerViewEventMap {
2073
2701
  /**
2074
2702
  * Viewer initialized.
2075
2703
  */
2076
2704
  viewinit: CustomEvent<MarkerViewEventData>;
2705
+ /**
2706
+ * Viewer shown.
2707
+ */
2077
2708
  viewshow: CustomEvent<MarkerViewEventData>;
2709
+ /**
2710
+ * Viewer state restored.
2711
+ */
2078
2712
  viewrestorestate: CustomEvent<MarkerViewEventData>;
2079
2713
  }
2714
+ /**
2715
+ * Event data for {@link MarkerView}.
2716
+ */
2080
2717
  interface MarkerViewEventData {
2081
2718
  /**
2082
2719
  * {@link MarkerView} instance.
2083
2720
  */
2084
2721
  markerView: MarkerView;
2085
2722
  }
2723
+ /**
2724
+ * MarkerView is the main annotation viewer web component.
2725
+ *
2726
+ * @summary
2727
+ * The main annotation viewer web component.
2728
+ *
2729
+ * @group Components
2730
+ *
2731
+ * @example
2732
+ * To show dynamic annotation overlays on top of the original image you use `MarkerView`.
2733
+ * ```js
2734
+ * import { MarkerView } from '@markerjs/markerjs3';
2735
+ *
2736
+ * const markerView = new MarkerView();
2737
+ * markerView.targetImage = targetImg;
2738
+ * viewerContainer.appendChild(markerView);
2739
+ *
2740
+ * markerView.show(savedState);
2741
+ * ```
2742
+ */
2086
2743
  declare class MarkerView extends HTMLElement {
2087
2744
  private _contentContainer?;
2088
2745
  private _canvasContainer?;
@@ -2092,15 +2749,40 @@ declare class MarkerView extends HTMLElement {
2092
2749
  private width;
2093
2750
  private height;
2094
2751
  private _targetWidth;
2752
+ /**
2753
+ * Returns the target image width.
2754
+ */
2095
2755
  get targetWidth(): number;
2756
+ /**
2757
+ * Sets the target image width.
2758
+ */
2096
2759
  set targetWidth(value: number);
2097
2760
  private _targetHeight;
2761
+ /**
2762
+ * Returns the target image height.
2763
+ */
2098
2764
  get targetHeight(): number;
2765
+ /**
2766
+ * Sets the target image height.
2767
+ */
2099
2768
  set targetHeight(value: number);
2769
+ private _targetImageLoaded;
2100
2770
  private _targetImage;
2771
+ /**
2772
+ * Returns the target image.
2773
+ */
2101
2774
  get targetImage(): HTMLImageElement | undefined;
2775
+ /**
2776
+ * Sets the target image.
2777
+ */
2102
2778
  set targetImage(value: HTMLImageElement | undefined);
2779
+ /**
2780
+ * Marker types available for the viewer.
2781
+ */
2103
2782
  markerTypes: Array<typeof MarkerBase>;
2783
+ /**
2784
+ * Collection of markers currently displayed on the viewer.
2785
+ */
2104
2786
  markers: MarkerBase[];
2105
2787
  private _logoUI?;
2106
2788
  private _zoomLevel;
@@ -2127,7 +2809,16 @@ declare class MarkerView extends HTMLElement {
2127
2809
  private detachEvents;
2128
2810
  private detachWindowEvents;
2129
2811
  private getMarkerTypeByName;
2812
+ /**
2813
+ * Adds a new marker type to be available in the viewer.
2814
+ * @param markerType
2815
+ */
2130
2816
  registerMarkerType(markerType: typeof MarkerBase): void;
2817
+ private _stateToRestore;
2818
+ /**
2819
+ * Loads and shows previously saved annotation state.
2820
+ * @param state
2821
+ */
2131
2822
  show(state: AnnotationState): void;
2132
2823
  private scaleMarkers;
2133
2824
  /**
@@ -2148,21 +2839,73 @@ declare class MarkerView extends HTMLElement {
2148
2839
  removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => void, options?: boolean | EventListenerOptions | undefined): void;
2149
2840
  }
2150
2841
 
2842
+ /**
2843
+ * @module Renderer
2844
+ * @category API Reference
2845
+ */
2846
+
2847
+ /**
2848
+ * Renderer is used to rasterize annotations.
2849
+ *
2850
+ * @example
2851
+ * To render the annotation as a static image you use `Renderer`.
2852
+ *
2853
+ * ```js
2854
+ * import { MarkerArea, Renderer } from '@markerjs/markerjs3';
2855
+ * ```
2856
+ *
2857
+ * Just create an instance of it and pass the annotation state to the `rasterize()` method:
2858
+ *
2859
+ * ```js
2860
+ * const renderer = new Renderer();
2861
+ * renderer.targetImage = targetImg;
2862
+ * const dataUrl = await renderer.rasterize(markerArea.getState());
2863
+ *
2864
+ * const img = document.createElement('img');
2865
+ * img.src = dataUrl;
2866
+ *
2867
+ * someDiv.appendChild(img);
2868
+ * ```
2869
+ */
2151
2870
  declare class Renderer {
2152
2871
  private _mainCanvas?;
2153
2872
  private _editingTarget?;
2154
2873
  private _renderHelperContainer?;
2155
2874
  private _targetWidth;
2875
+ /**
2876
+ * Width of the target image.
2877
+ */
2156
2878
  get targetWidth(): number;
2879
+ /**
2880
+ * Width of the target image.
2881
+ */
2157
2882
  set targetWidth(value: number);
2158
2883
  private _targetHeight;
2884
+ /**
2885
+ * Height of the target image.
2886
+ */
2159
2887
  get targetHeight(): number;
2888
+ /**
2889
+ * Height of the target image.
2890
+ */
2160
2891
  set targetHeight(value: number);
2161
2892
  private _targetImageLoaded;
2162
2893
  private _targetImage;
2894
+ /**
2895
+ * Target image to render annotations on.
2896
+ */
2163
2897
  get targetImage(): HTMLImageElement | undefined;
2898
+ /**
2899
+ * Target image to render annotations on.
2900
+ */
2164
2901
  set targetImage(value: HTMLImageElement | undefined);
2902
+ /**
2903
+ * Marker types available for rendering.
2904
+ */
2165
2905
  markerTypes: Array<typeof MarkerBase>;
2906
+ /**
2907
+ * Array of markers to render.
2908
+ */
2166
2909
  markers: MarkerBase[];
2167
2910
  private _isInitialized;
2168
2911
  /**
@@ -2205,10 +2948,24 @@ declare class Renderer {
2205
2948
  private addTargetImage;
2206
2949
  private addNewMarker;
2207
2950
  private getMarkerTypeByName;
2951
+ /**
2952
+ * Adds a new marker type to the list of available marker types.
2953
+ * @param markerType - Marker type to register.
2954
+ */
2208
2955
  registerMarkerType(markerType: typeof MarkerBase): void;
2956
+ /**
2957
+ * Restores the annotation state.
2958
+ * @param state - Annotation state to restore.
2959
+ */
2209
2960
  restoreState(state: AnnotationState): void;
2210
2961
  private scaleMarkers;
2962
+ /**
2963
+ * Rasterizes the annotation.
2964
+ * @param state - annotation state to render.
2965
+ * @param targetCanvas - optional target canvas to render the annotation on.
2966
+ * @returns
2967
+ */
2211
2968
  rasterize(state: AnnotationState, targetCanvas?: HTMLCanvasElement): Promise<string>;
2212
2969
  }
2213
2970
 
2214
- export { type AnnotationState, ArrowMarker, ArrowMarkerEditor, type ArrowMarkerState, type ArrowType, CalloutMarker, CalloutMarkerEditor, type CalloutMarkerState, CaptionFrameMarker, CaptionFrameMarkerEditor, type CaptionFrameMarkerState, CheckImageMarker, type ColorType, CoverMarker, CustomImageMarker, EllipseFrameMarker, EllipseMarker, type FontSize, FrameMarker, FreehandMarker, FreehandMarkerEditor, type FreehandMarkerState, Grip, HighlightMarker, type IPoint, ImageMarkerBase, type ImageMarkerBaseState, ImageMarkerEditor, type ImageType, LineMarker, LinearMarkerBase, type LinearMarkerBaseState, LinearMarkerEditor, MarkerArea, type MarkerAreaEventData, type MarkerAreaEventMap, MarkerBase, MarkerBaseEditor, type MarkerBaseState, type MarkerEditorProperties, type MarkerEditorState, MarkerView, type MarkerViewEventData, type MarkerViewEventMap, MeasurementMarker, PolygonMarker, PolygonMarkerEditor, type PolygonMarkerState, RectangularBoxMarkerBase, type RectangularBoxMarkerBaseState, Renderer, ResizeGrip, RotateGrip, ShapeMarkerBase, type ShapeMarkerBaseState, ShapeMarkerEditor, ShapeOutlineMarkerBase, type ShapeOutlineMarkerBaseState, ShapeOutlineMarkerEditor, SvgHelper, TextMarker, TextMarkerEditor, type TextMarkerState, XImageMarker };
2971
+ export { type AnnotationState, ArrowMarker, ArrowMarkerEditor, type ArrowMarkerState, type ArrowType, type BlurHandler, CalloutMarker, CalloutMarkerEditor, type CalloutMarkerState, CaptionFrameMarker, CaptionFrameMarkerEditor, type CaptionFrameMarkerState, CheckImageMarker, CoverMarker, CustomImageMarker, EllipseFrameMarker, EllipseMarker, type FontSize, FrameMarker, FreehandMarker, FreehandMarkerEditor, type FreehandMarkerState, Grip, type GripLocation, HighlightMarker, type IPoint, type ISize, type ITransformMatrix, ImageMarkerBase, type ImageMarkerBaseState, ImageMarkerEditor, type ImageType, LineMarker, LinearMarkerBase, type LinearMarkerBaseState, LinearMarkerEditor, MarkerArea, type MarkerAreaEventData, type MarkerAreaEventMap, type MarkerAreaMode, MarkerBase, MarkerBaseEditor, type MarkerBaseState, type MarkerCreationStyle, type MarkerEditorEventData, type MarkerEditorProperties, type MarkerEditorState, type MarkerStage, MarkerView, type MarkerViewEventData, type MarkerViewEventMap, MeasurementMarker, PolygonMarker, PolygonMarkerEditor, type PolygonMarkerState, RectangularBoxMarkerBase, type RectangularBoxMarkerBaseState, Renderer, ResizeGrip, RotateGrip, ShapeMarkerBase, type ShapeMarkerBaseState, ShapeMarkerEditor, ShapeOutlineMarkerBase, type ShapeOutlineMarkerBaseState, ShapeOutlineMarkerEditor, SvgHelper, TextBlock, TextBlockEditor, type TextChangedHandler, TextMarker, TextMarkerEditor, type TextMarkerState, XImageMarker };