FreeText & Callout Annotations

FreeText annotations allow users to write text onto the page. Callout annotations are actually FreeText annotations underneath. The main difference is they will have a line ending that points to something on the page that is meant to be referenced.

Contrary to most rectangular annotations, FreeText annotations are actually composed of points as opposed to a rectangle. A FreeText annotation is initialized with two points whereas a callout has a total of five points (one each for joint, knee, and end). Another difference between the two is the intent of the annotation which indicates what type of annotation it should be (callout or normal FreeText).

1WebViewer(...)
2  .then(instance => {
3    const { documentViewer, annotationManager, Annotations } = instance.Core;
4
5    documentViewer.addEventListener('annotationsLoaded', () => {
6      const annot = new Annotations.FreeTextAnnotation(Annotations.FreeTextAnnotation.Intent.FreeText, {
7        PageNumber: 1,
8        X: 100,
9        Y: 50,
10        Width: 200,
11        Height: 50,
12        TextAlign: 'center',
13        TextVerticalAlign: 'center',
14        TextColor: new Annotations.Color(255, 0, 0, 1),
15        StrokeColor: new Annotations.Color(0, 255, 0, 1),
16      });
17
18      annot.setContents(`Visited: ${new Date()}`);
19
20      annotationManager.addAnnotation(annot);
21      annotationManager.redrawAnnotation(annot);
22    });
23  });

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.on('annotationsLoaded', () => {
6      const annot = new Annotations.FreeTextAnnotation(); // Intent defaults to FreeText
7      annot.PageNumber = 1;
8      annot.X = 100;
9      annot.Y = 50;
10      annot.Width = 200;
11      annot.Height = 50;
12      annot.TextAlign = 'center';
13      annot.TextColor = new Annotations.Color(255, 0, 0, 1);
14      annot.StrokeColor = new Annotations.Color(0, 255, 0, 1);
15
16      annot.setContents(`Visited: ${new Date()}`);
17
18      annotManager.addAnnotation(annot);
19      annotManager.redrawAnnotation(annot);
20    });
21  });

1WebViewer(...)
2  .then(instance => {
3    const { documentViewer, annotationManager, Annotations } = instance.Core;
4
5    documentViewer.addEventListener('annotationsLoaded', () => {
6      const annot = new Annotations.FreeTextAnnotation(Annotations.FreeTextAnnotation.Intent.FreeTextCallout, {
7        PageNumber: 1,
8        TextAlign: 'center',
9        TextVerticalAlign: 'center',
10        TextColor: new Annotations.Color(255, 0, 0, 1),
11        StrokeColor: new Annotations.Color(0, 255, 0, 1),
12      });
13
14      annot.setPathPoint(0, 500, 25);  // Callout ending (start)
15      annot.setPathPoint(1, 425, 75);  // Callout knee
16      annot.setPathPoint(2, 300, 75);  // Callout joint
17      annot.setPathPoint(3, 100, 50);  // Top-left point
18      annot.setPathPoint(4, 300, 100); // Bottom-right point
19
20      annot.setContents(`Visited: ${new Date()}`);
21
22      annotationManager.addAnnotation(annot);
23      annotationManager.redrawAnnotation(annot);
24    });
25  });

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.on('annotationsLoaded', () => {
6      const annot = new Annotations.FreeTextAnnotation(Annotations.FreeTextAnnotation.Intent.FreeTextCallout);
7      annot.PageNumber = 1;
8      annot.TextAlign = 'center';
9      annot.TextColor = new Annotations.Color(255, 0, 0, 1);
10      annot.StrokeColor = new Annotations.Color(0, 255, 0, 1);
11
12      annot.setPathPoint(0, 500, 25);  // Callout ending (start)
13      annot.setPathPoint(1, 425, 75);  // Callout knee
14      annot.setPathPoint(2, 300, 75);  // Callout joint
15      annot.setPathPoint(3, 100, 50);  // Top-left point
16      annot.setPathPoint(4, 300, 100); // Bottom-right point
17
18      annot.setContents(`Visited: ${new Date()}`);
19
20      annotManager.addAnnotation(annot);
21      annotManager.redrawAnnotation(annot);
22    });
23  });

Element name: freetext

1<freetext page="0" rect="163.440,623.270,348.060,704.660" flags="print" name="5b9b1430-c04f-bc6d-5457-f90c7793997f" title="Guest" subject="Free Text" date="D:20220525164654-07'00'" width="0.75" creationdate="D:20220525164652-07'00'" TextColor="#E44234" FontSize="12">
2  <trn-custom-data bytes="{"trn-wrapped-text-lines":"[\"Insert text here \"]"}"/>
3  <contents>Insert text here</contents>
4  <contents-richtext>
5      <body>
6          <p>
7              <span>Insert text here</span>
8          </p>
9      </body>
10  </contents-richtext>
11  <appearance xmlns="http://www.w3.org/1999/xhtml">...</appearance>
12  <defaultappearance>0.894 0.259 0.204 rg /Helvetica 12 Tf</defaultappearance>
13  <defaultstyle>font: Helvetica 12pt; text-align: left; text-vertical-align: top; color: #E44234</defaultstyle>
14</freetext>

Gets or sets the page number of a document that the annotation appears on.

Gets or sets the annotation's x-axis position.

This property can be initialized through an object initializer but works best on regular FreeText annotations.

Gets or sets the annotation's y-axis position.

This property can be initialized through an object initializer but works best on regular FreeText annotations.

Gets or sets the width of the annotation.

This property can be initialized through an object initializer but works best on regular FreeText annotations. Setting this on a callout will scale it up or down.

Gets or sets the height of the annotation.

This property can be initialized through an object initializer but works best on regular FreeText annotations. Setting this on a callout will scale it up or down.

For the full list of properties, please visit the annotation's API docs.

An enum with possible auto-size types. See setAutoSizeType to change the autosizing behavior.

Values:

• NONE
• AUTO
• FIXED_WIDTH
• FIXED_HEIGHT

An enum with possible freetext intents.

Values:

• FreeText
• FreeTextCallout

The font to use for the annotation's text. Fonts supported by the canvas/CSS only.

The font size to use for the annotation's text, specified like a CSS font size.

The horizontal alignment of the annotation's text.

Values:

• left
• center
• right
• justify

The vertical alignment of the annotation's text (top, bottom, center). Default: top.

The color of the text in the annotation.

Gets or sets the color of the annotation's stroke.

Gets or sets the color of the annotation's interior.

Gets or sets the border style of an annotation. Possible styles include:

• solid
• dash
• cloudy

Gets or sets the border dash style of an annotation. This expects a string representing the length of dashes and spacing inbetween, delimited by commas (ex. 3, 3). You can specify any amount of lengths but, an odd number of values will be made even by cloning it as a second set. To understand further, you can read more about the setLineDash API.

Gets or sets the width of the annotation's stroke outline.

Object that contains all the flags to customize the auto-sizing behavior.

The author of the annotation.

Gets or sets the annotation's stroke color.

Gets or sets whether the annotation is hidden.

Gets or sets whether the annotation is invisible, only if it is an unknown annotation type. Generally for hiding annotations you should use "Hidden".

Gets or sets whether any parts of the annotation drawn outside of the rect are clickable.

Gets or sets whether the annotation should be listed in annotation lists. If set to false, the annotation will also become unselectable.

Gets or sets whether the annotation is locked or not. If it's locked it can't be edited or deleted, but the note can be edited.

Gets or sets whether the annotation contents are locked or not. If the contents are locked then note can't be edited but the annotation can be edited or deleted.

Gets or sets if this annotation can be deleted.

Gets or sets whether or not the annotation can be moved.

Gets or sets if this annotation can be resized by the user.

Gets or sets if this annotation can be rotated.

Gets or sets whether the annotation is visible on the screen. Differs from Hidden in that it can still be printed if the print flag is set.

Gets or sets if this annotation scales with the page.

Gets or sets whether the annotation should be displayed when printing the page.

Gets or sets whether the annotation is readonly or not. If it's readonly both the annotation itself and its note can't be edited or deleted.

Gets or sets whether the ToggleNoView flag is set on the annotation.

To read the path or points of the FreeText and/or callout annotation, you can use getPath to get an array of points. FreeText annotations will contain two points whereas callouts will contain five (line ending, knee, joint, top left of content box, and bottom right of content box).

1WebViewer(...)
2  .then(instance => {
3    const { documentViewer, annotationManager, Annotations } = instance.Core;
4
5    documentViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotationManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          const points = annot.getPath();
10          points.forEach(point => {
11            // Work with points
12          });
13        }
14      });
15    });
16  });

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          const points = annot.getPath();
10          points.forEach(point => {
11            // Work with points
12          });
13        }
14      });
15    });
16  });

Rather than setting individual points to set up a FreeText annotation, it is possible to set the entire path of points with setPath.

To know what kind of FreeTextAnnotation you are working with, you can read the intent with getIntent which can be matched to either FreeText or FreeTextCallout.

You can set the intent of a FreeText annotation with the setIntent API after initialization. You will need to adjust the path of the annotation to have the exact points it requires or the annotation may not render properly.

1WebViewer(...)
2  .then(instance => {
3    const { documentViewer, annotationManager, Annotations } = instance.Core;
4
5    documentViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotationManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          annot.setIntent(Annotations.FreeTextAnnotation.Intent.FreeText);
10          annot.setPath(annot.getPath().slice(0, 2));
11        }
12      });
13    });
14  });

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          annot.setIntent(Annotations.FreeTextAnnotation.Intent.FreeText);
10          annot.setPath(annot.getPath().slice(0, 2));
11        }
12      });
13    });
14  });

As the content of the FreeText annotation is the primary focus, there should be a way to read it. This can be done with the getContents API.

1WebViewer(...)
2  .then(instance => {
3    const { documentViewer, annotationManager, Annotations } = instance.Core;
4
5    documentViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotationManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          const contents = annot.getContents();
10          // Check contents
11        }
12      });
13    });
14  });

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          const contents = annot.getContents();
10          // Check contents
11        }
12      });
13    });
14  });

Most of the time, you will be creating a FreeText annotation with text. To set the text, you use the setContents method to provide the string content.

If you know which point of the annotation path you would like to get, you can use getPathPoint with the point index to retrieve the point.

Setting the path points on the freetext/callout annotation can be done through the setPathPoint. This can be used to initialize the points of a the annotation if that was not done at the start. Please note that there will be two points in the annotation path by default, initializing it in the top left corner with a size of one.

1WebViewer(...)
2  .then(instance => {
3    const { documentViewer, annotationManager, Annotations } = instance.Core;
4
5    documentViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotationManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          annot.setPathPoint(0, 50, 100);
10          annot.setPathPoint(1, 250, 150);
11        }
12      });
13    });
14  });

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          annot.setPathPoint(0, 50, 100);
10          annot.setPathPoint(1, 250, 150);
11        }
12      });
13    });
14  });

This is only for callout annotations. Callout annotations have a default line ending that is an arrow. In actuality, this is the start of the path and can be changed with the setStartStyle. You can find the possible line endings with the LineEndType constant.

1WebViewer(...)
2  .then(instance => {
3    const { documentViewer, annotationManager, Annotations } = instance.Core;
4
5    documentViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotationManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          annot.setLineEndType(Annotations.LineEndType.DIAMOND);
10        }
11      });
12    });
13  });

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          annot.setLineEndType('Diamond');
10        }
11      });
12    });
13  });

This method is used to switch the font size behavior of the free text annotation to "auto," which means that the font size will adapt dynamically to the size of the annotation's bounding box when it is resized.

1WebViewer(...)
2  .then(instance => {
3    const { documentViewer, annotationManager, Annotations } = instance.Core;
4
5    documentViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotationManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          annot.switchToAutoFontSize();
10        }
11      });
12    });
13  });

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.addEventListener('annotationsLoaded', () => {
6      const annotList = annotManager.getAnnotationsList();
7      annotList.forEach(annot => {
8        if (annot instanceof Annotations.FreeTextAnnotation) {
9          annot.FontSize = '0px'
10        }
11      });
12    });
13  });

This method retrieves the font size that has been dynamically calculated to fit the content within the bounding box of the free text annotation when switchToAutoFontSize is used to enable auto-sizing of the font size. If switchToAutoFontSize has not been called, it will return the current font size.

1WebViewer(...)
2  .then(instance => {
3    const { annotationManager, Annotations } = instance.Core;
4
5    annotationManager.addEventListener('annotationSelected', (annotations, action) => {
6        if (action === 'selected' && annotations[0] instanceof Annotations.FreeTextAnnotation) {
7           annotations[0].switchToAutoFontSize(); 
8        }
9    });
10
11    annotationManager.addEventListener('annotationChanged', (annotations, action) => {
12        if (action === 'modify' && annotations[0] instanceof Annotations.FreeTextAnnotation) {
13          console.log(annotations[0].getCalculatedFontSize());
14        }
15    });
16  });

FreeText annotations created through the FreeTextCreateTool can be created one of two ways: drawing a rectangle or by clicking. This changes how FreeText annotations resize relative to their content. By creating a FreeText annotation by drawing a rectangle, it has a fixed size and does not autosize to content. The latter will resize relative to the content.