PdfAnnotationCollection Class
The annotations of a page: the /Annots array (ISO 32000-2, 12.5).
public sealed class PdfAnnotationCollection : IEnumerable<PdfAnnotation>, IReadOnlyCollection<PdfAnnotation>, IReadOnlyList<PdfAnnotation>, IEnumerableRemarks
The annotations are read once and kept until the /Annots array changes, through the collection or the object model: PdfAnnotationCollection.Count and the indexer do not read the array again, and an annotation is the same instance until then.
- Implements
Properties
| Name | Description |
|---|---|
| Count | Gets the number of annotations. |
Indexers
| Name | Description |
|---|---|
| this[int] | Gets an annotation. |
this[int]
PdfAnnotationCollection.csGets an annotation.
public PdfAnnotation this[int index] { get; }Methods
| Name | Description |
|---|---|
| AddCaret(PdfRectangle, string?, PdfColor?) | Adds a caret annotation (12.5.6.11): a symbol that marks where text is to be inserted. |
| AddCircle(PdfRectangle, PdfColor?, PdfColor?, double) | Adds a circle annotation (12.5.6.8): an ellipse inscribed in a rectangle. |
| AddFileAttachment(PdfRectangle, PdfEmbeddedFile, PdfFileAttachmentIcon) | Adds a file attachment annotation (12.5.6.15) that holds a file of the document, such as a file of PdfDocument.EmbeddedFiles. |
| AddFileAttachment(PdfRectangle, string, ReadOnlySpan<byte>, PdfEmbeddedFileOptions?, PdfFileAttachmentIcon) | Adds a file attachment annotation (12.5.6.15) that embeds a new file. |
| AddFreeText(PdfRectangle, string, PdfStandardFont, double, PdfColor?) | Adds a free text annotation (12.5.6.6): a text drawn on the page, in a box with a border. |
| AddInk(IEnumerable<IEnumerable<PdfPoint>>, PdfColor?, double) | Adds an ink annotation (12.5.6.13): freehand strokes, as drawn with a pen, with round caps and joins. |
| AddLine(PdfPoint, PdfPoint, PdfColor?, double, PdfLineEnding, PdfLineEnding) | Adds a line annotation (12.5.6.7): a straight line, with endings such as arrows. |
| AddLink(PdfRectangle, PdfDestination) | Adds a link that goes to a destination of the document. |
| AddLink(PdfRectangle, Uri) | Adds a link that opens a URI. |
| AddNote(PdfPoint, string, PdfColor?) | Adds a note (a text annotation, 12.5.6.4): an icon that opens a text, drawn with the color. |
| AddPolyLine(IEnumerable<PdfPoint>, PdfColor?, double, PdfLineEnding, PdfLineEnding) | Adds a polyline annotation (12.5.6.9): connected straight lines, with endings such as arrows at the first and last vertices. |
| AddPolygon(IEnumerable<PdfPoint>, PdfColor?, PdfColor?, double) | Adds a polygon annotation (12.5.6.9): a closed shape of vertices. |
| AddPopup(PdfMarkupAnnotation, PdfRectangle, bool) | Adds the pop-up annotation of a markup annotation (12.5.6.14): the window that shows its text, and sets its PdfMarkupAnnotation.Popup. |
| AddRedaction(IEnumerable<PdfRectangle>, string?, PdfColor?) | Adds a redaction annotation (12.5.6.23): marks regions whose content is to be removed. The content stays until the redaction is applied, by PdfDocument.ApplyRedactions or by a viewer; until then, the regions are outlined in red. |
| AddReply(PdfMarkupAnnotation, string, string?) | Adds a reply to a markup annotation (12.5.6.2): a text annotation in reply to it (/IRT), at the same place. Viewers list the replies in the thread of the annotation; the reply has an empty appearance, so that it does not draw a second icon. |
| AddSquare(PdfRectangle, PdfColor?, PdfColor?, double) | Adds a square annotation (12.5.6.8): a rectangle. |
| AddStamp(PdfRectangle, string, PdfColor?) | Adds a rubber stamp annotation (12.5.6.12): a word, such as APPROVED or DRAFT, in a frame with rounded corners. |
| AddTextMarkup(PdfTextMarkupKind, IEnumerable<PdfRectangle>, PdfColor?, string?) | Adds a text markup annotation (12.5.6.10): a highlight, an underline, a squiggly underline or a strikeout of regions of the page, such as the lines of a text. |
| GetEnumerator() | Returns an enumerator over the annotations. |
| Remove(PdfAnnotation) | Removes an annotation from the page, with the references that would keep it in a saved file: its pop-up annotation, the /IRT and /Popup entries of the other annotations of the page that point to it, the object references of the structure tree, and, for a widget, its entry in its form field. |
| System.Collections.IEnumerable.GetEnumerator() |
AddCaret(PdfRectangle, string?, PdfColor?)
PdfAnnotationCollection.csAdds a caret annotation (12.5.6.11): a symbol that marks where text is to be inserted.
public PdfCaretAnnotation AddCaret(PdfRectangle rectangle, string? text = null, PdfColor? color = null)Parameters
rectanglePdfRectangle- The rectangle of the caret, in default user space.
textstring?- The text to insert, or a comment, or
null. colorPdfColor?- The color of the caret, or
nullfor blue.
Returns
PdfCaretAnnotation The annotation.
AddCircle(PdfRectangle, PdfColor?, PdfColor?, double)
PdfAnnotationCollection.csAdds a circle annotation (12.5.6.8): an ellipse inscribed in a rectangle.
public PdfCircleAnnotation AddCircle(PdfRectangle rectangle, PdfColor? color = null, PdfColor? interiorColor = null, double width = 1d)Parameters
rectanglePdfRectangle- The rectangle, in default user space: the border is drawn inside it.
colorPdfColor?- The color of the border, or
nullfor red. interiorColorPdfColor?- The color that fills the ellipse, or
nullfor none. widthdouble- The width of the border, in points; 0 for none.
Returns
PdfCircleAnnotation The annotation.
Exceptions
ArgumentOutOfRangeExceptionwidthis negative or not finite.
AddFileAttachment overloads
AddFileAttachment(PdfRectangle, PdfEmbeddedFile, PdfFileAttachmentIcon)
PdfAnnotationCollection.csAdds a file attachment annotation (12.5.6.15) that holds a file of the document, such as a file of PdfDocument.EmbeddedFiles.
public PdfFileAttachmentAnnotation AddFileAttachment(PdfRectangle rectangle, PdfEmbeddedFile file, PdfFileAttachmentIcon icon = PdfFileAttachmentIcon.PushPin)Parameters
rectanglePdfRectangle- The region of the icon, in default user space.
filePdfEmbeddedFile- The file.
iconPdfFileAttachmentIcon- The icon of the annotation.
Returns
PdfFileAttachmentAnnotation The annotation. Its PdfAnnotation.Contents, the text that describes it, is the description of the file or its name.
Exceptions
ArgumentException- The file is not an indirect object of the document.
AddFileAttachment(PdfRectangle, string, ReadOnlySpan<byte>, PdfEmbeddedFileOptions?, PdfFileAttachmentIcon)
PdfAnnotationCollection.csAdds a file attachment annotation (12.5.6.15) that embeds a new file.
public PdfFileAttachmentAnnotation AddFileAttachment(PdfRectangle rectangle, string fileName, ReadOnlySpan<byte> data, PdfEmbeddedFileOptions? options = null, PdfFileAttachmentIcon icon = PdfFileAttachmentIcon.PushPin)Parameters
rectanglePdfRectangle- The region of the icon, in default user space.
fileNamestring- The name of the file.
dataReadOnlySpan<byte>- The content of the file.
optionsPdfEmbeddedFileOptions?- The attributes of the file, or
nullfor the defaults. iconPdfFileAttachmentIcon- The icon of the annotation.
Returns
PdfFileAttachmentAnnotation The annotation. Its PdfAnnotation.Contents, the text that describes it, is the description of the file or its name.
Exceptions
ArgumentExceptionfileNameis empty, or the MIME type is not valid.
AddFreeText(PdfRectangle, string, PdfStandardFont, double, PdfColor?)
PdfAnnotationCollection.csAdds a free text annotation (12.5.6.6): a text drawn on the page, in a box with a border.
public PdfMarkupAnnotation AddFreeText(PdfRectangle rectangle, string text, PdfStandardFont font = PdfStandardFont.Helvetica, double fontSize = 12d, PdfColor? color = null)Parameters
rectanglePdfRectangle- The box, in default user space.
textstring- The text: it is broken into lines that fit the box.
fontPdfStandardFont- The font, a standard font: the default appearance string of the annotation (
/DA) names it. fontSizedouble- The font size.
colorPdfColor?- The color of the text and of the border, or
nullfor black.
Returns
PdfMarkupAnnotation The annotation.
Exceptions
ArgumentException- A character of the text has no glyph in the font.
AddInk(IEnumerable<IEnumerable<PdfPoint>>, PdfColor?, double)
PdfAnnotationCollection.csAdds an ink annotation (12.5.6.13): freehand strokes, as drawn with a pen, with round caps and joins.
public PdfInkAnnotation AddInk(IEnumerable<IEnumerable<PdfPoint>> strokes, PdfColor? color = null, double width = 1d)Parameters
strokesIEnumerable<IEnumerable<PdfPoint>>- The strokes: each one a list of points, in default user space.
colorPdfColor?- The color of the strokes, or
nullfor red. widthdouble- The width of the strokes, in points.
Returns
PdfInkAnnotation The annotation.
Exceptions
ArgumentException- There is no stroke, a stroke is empty, or a coordinate is not a finite number.
ArgumentOutOfRangeExceptionwidthis negative or not finite.
AddLine(PdfPoint, PdfPoint, PdfColor?, double, PdfLineEnding, PdfLineEnding)
PdfAnnotationCollection.csAdds a line annotation (12.5.6.7): a straight line, with endings such as arrows.
public PdfLineAnnotation AddLine(PdfPoint start, PdfPoint end, PdfColor? color = null, double width = 1d, PdfLineEnding startEnding = PdfLineEnding.None, PdfLineEnding endEnding = PdfLineEnding.None)Parameters
startPdfPoint- The start of the line, in default user space.
endPdfPoint- The end of the line, in default user space.
colorPdfColor?- The color of the line, or
nullfor red. widthdouble- The width of the line, in points.
startEndingPdfLineEnding- The ending at
start. endEndingPdfLineEnding- The ending at
end.
Returns
PdfLineAnnotation The annotation. Its closed endings are filled with the color of the line (PdfLineAnnotation.InteriorColor).
Exceptions
ArgumentException- A coordinate is not a finite number.
ArgumentOutOfRangeExceptionwidthis negative or not finite.
AddLink overloads
AddLink(PdfRectangle, PdfDestination)
PdfAnnotationCollection.csAdds a link that goes to a destination of the document.
public PdfLinkAnnotation AddLink(PdfRectangle rectangle, PdfDestination destination)Parameters
rectanglePdfRectangle- The region of the page, in default user space.
destinationPdfDestination- The destination.
Returns
PdfLinkAnnotation The link.
AddLink(PdfRectangle, Uri)
PdfAnnotationCollection.csAdds a link that opens a URI.
public PdfLinkAnnotation AddLink(PdfRectangle rectangle, Uri uri)Parameters
rectanglePdfRectangle- The region of the page, in default user space.
uriUri- The URI: an absolute URI, written as 7-bit ASCII (12.6.4.8): an internationalized host in its IDNA ASCII form (
xn--labels), the other non-ASCII characters percent-encoded as UTF-8.
Returns
PdfLinkAnnotation The link.
AddNote(PdfPoint, string, PdfColor?)
PdfAnnotationCollection.csAdds a note (a text annotation, 12.5.6.4): an icon that opens a text, drawn with the color.
public PdfMarkupAnnotation AddNote(PdfPoint position, string text, PdfColor? color = null)Parameters
positionPdfPoint- The lower-left corner of the icon, in default user space; the icon is 20 x 20.
textstring- The text of the note.
colorPdfColor?- The color of the icon, or
nullfor yellow.
Returns
PdfMarkupAnnotation The note.
AddPolyLine(IEnumerable<PdfPoint>, PdfColor?, double, PdfLineEnding, PdfLineEnding)
PdfAnnotationCollection.csAdds a polyline annotation (12.5.6.9): connected straight lines, with endings such as arrows at the first and last vertices.
public PdfPolyLineAnnotation AddPolyLine(IEnumerable<PdfPoint> vertices, PdfColor? color = null, double width = 1d, PdfLineEnding startEnding = PdfLineEnding.None, PdfLineEnding endEnding = PdfLineEnding.None)Parameters
verticesIEnumerable<PdfPoint>- The vertices, in default user space: at least 2.
colorPdfColor?- The color of the lines, or
nullfor red. widthdouble- The width of the lines, in points.
startEndingPdfLineEnding- The ending at the first vertex.
endEndingPdfLineEnding- The ending at the last vertex.
Returns
PdfPolyLineAnnotation The annotation. Its closed endings are filled with the color of the lines.
Exceptions
ArgumentException- There are fewer than 2 vertices, or a coordinate is not a finite number.
ArgumentOutOfRangeExceptionwidthis negative or not finite.
AddPolygon(IEnumerable<PdfPoint>, PdfColor?, PdfColor?, double)
PdfAnnotationCollection.csAdds a polygon annotation (12.5.6.9): a closed shape of vertices.
public PdfPolygonAnnotation AddPolygon(IEnumerable<PdfPoint> vertices, PdfColor? color = null, PdfColor? interiorColor = null, double width = 1d)Parameters
verticesIEnumerable<PdfPoint>- The vertices, in default user space: at least 2.
colorPdfColor?- The color of the border, or
nullfor red. interiorColorPdfColor?- The color that fills the polygon, or
nullfor none. widthdouble- The width of the border, in points; 0 for none.
Returns
PdfPolygonAnnotation The annotation.
Exceptions
ArgumentException- There are fewer than 2 vertices, or a coordinate is not a finite number.
ArgumentOutOfRangeExceptionwidthis negative or not finite.
AddPopup(PdfMarkupAnnotation, PdfRectangle, bool)
PdfAnnotationCollection.csAdds the pop-up annotation of a markup annotation (12.5.6.14): the window that shows its text, and sets its PdfMarkupAnnotation.Popup.
public PdfPopupAnnotation AddPopup(PdfMarkupAnnotation parent, PdfRectangle rectangle, bool isOpen = false)Parameters
parentPdfMarkupAnnotation- The markup annotation, on this page.
rectanglePdfRectangle- The rectangle of the window, in default user space.
isOpenbool- Whether the window is initially open.
Returns
PdfPopupAnnotation The pop-up annotation.
Exceptions
ArgumentException- The annotation is not on this page.
AddRedaction(IEnumerable<PdfRectangle>, string?, PdfColor?)
PdfAnnotationCollection.csAdds a redaction annotation (12.5.6.23): marks regions whose content is to be removed. The content stays until the redaction is applied, by PdfDocument.ApplyRedactions or by a viewer; until then, the regions are outlined in red.
public PdfRedactAnnotation AddRedaction(IEnumerable<PdfRectangle> regions, string? overlayText = null, PdfColor? interiorColor = null)Parameters
regionsIEnumerable<PdfRectangle>- The regions, in default user space.
overlayTextstring?- The text drawn in the regions once they are redacted, or
null. interiorColorPdfColor?- The color that fills the regions once they are redacted, or
nullfor black.
Returns
PdfRedactAnnotation The annotation.
Exceptions
ArgumentException- There is no region.
AddReply(PdfMarkupAnnotation, string, string?)
PdfAnnotationCollection.csAdds a reply to a markup annotation (12.5.6.2): a text annotation in reply to it (/IRT), at the same place. Viewers list the replies in the thread of the annotation; the reply has an empty appearance, so that it does not draw a second icon.
public PdfTextAnnotation AddReply(PdfMarkupAnnotation parent, string text, string? author = null)Parameters
parentPdfMarkupAnnotation- The annotation, on this page.
textstring- The text of the reply.
authorstring?- The author of the reply, or
null.
Returns
PdfTextAnnotation The reply.
Exceptions
ArgumentException- The annotation is not on this page.
AddSquare(PdfRectangle, PdfColor?, PdfColor?, double)
PdfAnnotationCollection.csAdds a square annotation (12.5.6.8): a rectangle.
public PdfSquareAnnotation AddSquare(PdfRectangle rectangle, PdfColor? color = null, PdfColor? interiorColor = null, double width = 1d)Parameters
rectanglePdfRectangle- The rectangle, in default user space: the border is drawn inside it.
colorPdfColor?- The color of the border, or
nullfor red. interiorColorPdfColor?- The color that fills the rectangle, or
nullfor none. widthdouble- The width of the border, in points; 0 for none.
Returns
PdfSquareAnnotation The annotation.
Exceptions
ArgumentOutOfRangeExceptionwidthis negative or not finite.
AddStamp(PdfRectangle, string, PdfColor?)
PdfAnnotationCollection.csAdds a rubber stamp annotation (12.5.6.12): a word, such as APPROVED or DRAFT, in a frame with rounded corners.
public PdfMarkupAnnotation AddStamp(PdfRectangle rectangle, string text, PdfColor? color = null)Parameters
rectanglePdfRectangle- The rectangle of the stamp, in default user space.
textstring- The text of the stamp: it is fitted in the rectangle.
colorPdfColor?- The color of the stamp, or
nullfor red.
Returns
PdfMarkupAnnotation The annotation. Its /Name is Draft, Approved... when the text is the name of a standard stamp.
Exceptions
ArgumentException- The text is empty, or a character of the text has no glyph in Helvetica Bold.
AddTextMarkup(PdfTextMarkupKind, IEnumerable<PdfRectangle>, PdfColor?, string?)
PdfAnnotationCollection.csAdds a text markup annotation (12.5.6.10): a highlight, an underline, a squiggly underline or a strikeout of regions of the page, such as the lines of a text.
public PdfMarkupAnnotation AddTextMarkup(PdfTextMarkupKind kind, IEnumerable<PdfRectangle> regions, PdfColor? color = null, string? text = null)Parameters
kindPdfTextMarkupKind- The kind of markup.
regionsIEnumerable<PdfRectangle>- The regions, in default user space: one rectangle per line of the text, from its baseline to its top.
colorPdfColor?- The color, or
nullfor yellow (a highlight) or red. textstring?- The text of the annotation (a comment), or
null.
Returns
PdfMarkupAnnotation The annotation. Its appearance is drawn with the color; a highlight is multiplied with the content, so that the text stays readable.
Exceptions
ArgumentException- There is no region.
GetEnumerator()
PdfAnnotationCollection.csReturns an enumerator over the annotations.
public IEnumerator<PdfAnnotation> GetEnumerator()Returns
IEnumerator<PdfAnnotation> The enumerator.
Remove(PdfAnnotation)
PdfAnnotationCollection.csRemoves an annotation from the page, with the references that would keep it in a saved file: its pop-up annotation, the /IRT and /Popup entries of the other annotations of the page that point to it, the object references of the structure tree, and, for a widget, its entry in its form field.
public bool Remove(PdfAnnotation annotation)Parameters
annotationPdfAnnotation- The annotation.
Returns
bool true when the annotation was on the page.