# LispKit PDF

Library `(lispkit pdf)` provides an API for manipulating and analyzing PDF documents. The library supports creating PDF documents, managing pages, adding annotations, handling bookmarks, managing outlines, extracting content, and rendering pages.

A PDF document contains pages corresponding to the pages of a printed document. Each page contains text, images, hyperlinks and annotations. The page uses a coordinate system with 72 points to each printed inch. The coordinates originate at the bottom left of the page and increase going upward and to the right (as opposed to the coordinate system used by library `(lispkit draw)`. A PDF document also contains an outline which is a hierarchical data structure that defines the table of contents.

## PDF documents

(pdf? obj) [procedure]

Returns `#t` if obj is an object representing a PDF document. Otherwise, `#f` is returned.

(pdf-encrypted? doc) [procedure]

Returns `#t` if obj is an object representing an encrypted PDF document. Otherwise, `#f` is returned.

(pdf-locked? doc) [procedure]

Returns `#t` if obj is an object representing a locked PDF document. Otherwise, `#f` is returned. Only encrypted documents can be locked. Encrypted documents whose password is the empty string are unlocked automatically upon opening. PDF documents can be unlocked with the `pdf-unlock` procedure.

(make-pdf) [procedure]

Returns an object representing a new, empty PDF document.

(bytevector->pdf bvec) [procedure]
(bytevector->pdf bvec start)
(bytevector->pdf bvec start end)

Returns an object representing the PDF document defined by the bytes in bytevector bvev between start and end. If end is not provided, it is assumed to be the length of bvec. If start is not provided, it is assumed to be 0.

(load-pdf filepath) [procedure]

Loads the PDF file at path filepath and returns an object representing this PDF document. It is an error if the file at the given file path is not a PDF file.

(save-pdf filename doc) [procedure]
(save-pdf filename doc options)

Saves the PDF document represented by object doc into a file at path filepath. options is an association list supporting the following symbolic keys:

- `user-password`: The value is a user password string.
- `owner-password`: The value is a owner password string.
- `access-permissions`: The value is either `#f` (no permissions), `#t` (access permissions as defined by doc), or a list of the following symbols: `commenting` (allow commenting), `content-accessibility` (allow content accessibility), `content-copying` (allow copying of content), `document-assembly` (allow mutation of page structure), `document-changes` (allow changes to the PDF document), `form-field-entry` (allow setting form field values), `high-quality-printing` (support high quality printing), and `low-quality-printing` (support low quality printing).
- `burn-in-annotations`: If set to `#t`, annotations are burned into PDF pages.
- `optimize-for-screen`: If set to `#t`, the PDF document representation is optimized for screen usage.
- `save-images-as-jpeg`: If set to `#t`, images will all be represented as JPEGs.
- `save-text-from-ocr`: If set to `#t`, OCR will be applied to all pages and the text will be stored as an invisible but searchable and selectable layer on top of the page.

(pdf-unlock doc passwd) [procedure]

Unlocks the encrypted PDF document doc with password string passwd. After unlocking, predicate `pdf-locked?` will return `#f`.

(pdf->string doc) [procedure]

Extracts all text from the PDF document doc and returns it as a string.

(pdf->bytevector doc) [procedure]
(pdf->bytevector doc options)

Returns a bytevector representing the PDF document doc. options is an association list supporting the following symbolic keys:

- `user-password`: The value is a user password string.
- `owner-password`: The value is a owner password string.
- `access-permissions`: The value is either `#f` (no permissions), `#t` (access permissions as defined by doc), or a list of the following symbols: `commenting` (allow commenting), `content-accessibility` (allow content accessibility), `content-copying` (allow copying of content), `document-assembly` (allow mutation of page structure), `document-changes` (allow changes to the PDF document), `form-field-entry` (allow setting form field values), `high-quality-printing` (support high quality printing), and `low-quality-printing` (support low quality printing).
- `burn-in-annotations`: If set to `#t`, annotations are burned into PDF pages.
- `optimize-for-screen`: If set to `#t`, the PDF document representation is optimized for screen usage.
- `save-images-as-jpeg`: If set to `#t`, images will all be represented as JPEGs.
- `save-text-from-ocr`: If set to `#t`, OCR will be applied to all pages and the text will be stored as an invisible but searchable and selectable layer on top of the page.

(pdf-path doc) [procedure]

Returns the file path of PDF document doc if it exists. Otherwise, `#f` is returned.

(pdf-version doc) [procedure]

Returns the PDF version used for the representation of the PDF document doc as a pair of two numbers: (major . minor). Returns `#f` if a version is not available.

(pdf-attributes doc) [procedure]

Returns an association list of document-level attributes for the PDF document doc. Common attributes include `Creator` (the creator of the content as a string), `Producer` (the one who made this PDF as a string), `Author` (the author of this content as a string), `Title` (the title of this document as a string), `Subject` (the subject of this document as a string), `CreationDate` (the creation date of this document), `ModDate` (the modification date of this document), `Keywords` (a string describing keywords associated with this document).

(pdf-attribute-ref doc key) [procedure]
(pdf-attribute-ref doc key default)

Returns a value for a document-level attribute of PDF document doc identified by symbol key. Keys of common attributes are: `Creator`, `Producer`, `Author`, `Title`, `Subject`, `CreationDate`, `ModDate`, and `Keywords`. If the attribute identified by key does not exist, default is returned if it was provided. Otherwise, `#f` is returned.

(pdf-attribute-set! doc key value) [procedure]

Sets the value for a document-level attribute of PDF document doc identified by symbol key to value. Keys of common attributes are: `Creator`, `Producer`, `Author`, `Title`, `Subject`, `CreationDate`, `ModDate`, and `Keywords`.

(pdf-attribute-remove! doc key) [procedure]

Removes a document-level attribute from PDF document doc identified by symbol key. Keys of common attributes are: `Creator`, `Producer`, `Author`, `Title`, `Subject`, `CreationDate`, `ModDate`, and `Keywords`.

(pdf-access-permissions doc) [procedure]

Returns a list of symbols representing permissions enabled for the PDF document doc. The following symbols are supported:

- `commenting`: allow commenting,
- `content-accessibility`: allow content accessibility,
- `content-copying`: allow copying of content,
- `document-assembly`: allow mutation of page structure,
- `document-changes`: allow changes to the PDF document,
- `form-field-entry`: allow setting form field values,
- `high-quality-printing`: support high quality printing, and
- `low-quality-printing`: support low quality printing.

(pdf-page-count doc) [procedure]

Returns the number of pages of PDF document doc.

(pdf-pages doc) [procedure]

Returns a list of PDF pages for PDF document doc.

(pdf-page doc n) [procedure]

Returns the PDF page at index n of PDF document doc.

(pdf-insert-page! doc page) [procedure]
(pdf-insert-page! doc n page)

Inserts the given PDF page at index n into the PDF document doc. If n is not provided, the page is inserted at the end.

(pdf-remove-page! doc n) [procedure]

Removes the page at index n of PDF document doc.

(pdf-swap-page! doc n m) [procedure]

Swaps the page at index n with the page at index m of PDF document doc.

(pdf-page-index doc page) [procedure]

Returns the index of PDF page in the given PDF document doc. If page is not a valid PDF page in doc, `#f` is returned.

(pdf-outline doc) [procedure]

Returns the outline (table of contents) for the given PDF document doc or `#f` if there is no outline available for doc.

(pdf-outline-set! doc outline) [procedure]

Sets the outline (table of contents) for the given PDF document doc to outline. If outline is `#f`, then the table of contents of doc is removed.

## Predicates

(pdf-display-box? obj) [procedure]

Returns `#t` if obj is a valid display box specifier. Supported display box specifiers are: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`.

(pdf-line-style? obj) [procedure]

Returns `#t` if obj is a valid line style specifier. Supported line style specifiers are: `none`, `square`, `circle`, `diamond`, `open-arrow`, and `closed-arrow`.

(pdf-text-alignment? obj) [procedure]

Returns `#t` if obj is a valid text alignment specifier. Supported text alignment specifiers are: `left`, `right`, `center`, `justified`, and `natural`.

(pdf-icon-type? obj) [procedure]

Returns `#t` if obj is a valid icon type specifier. Supported icon type specifiers are: `comment`, `key`, `note`, `help`, `new-paragraph`, `paragraph`, and `insert`.

(pdf-markup-type? obj) [procedure]

Returns `#t` if obj is a valid markup type specifier. Supported markup type specifiers are: `highlight`, `strike-out`, `underline`, and `redact`.

## PDF pages

Pages in a PDF document are represented with `pdf-page` objects. A PDF page can either be inserted into a PDF document or it is standalone. If the page has been inserted, `pdf-page-number` returns the page number. If it has not been inserted, `pdf-page-number` returns `#f`. Page numbers are managed automatically and they potentially change when the pages of a PDF document are rearranged. Page labels on the other hand are customizable names for pages that are stable. The orientation of a PDF page is set by specifying a rotation.

A PDF page defines rectangular bounds for different types of display boxes of that page. Display boxes are identified via symbolic specifiers. Supported are: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`. The content of a PDF page is defined in terms of up to three different layers: besides the native PDF content, it is possible to set an underlay drawing which is drawn underneith the native content. If is also possible to define an overlay drawing which is drawn on top of the native content.

One type of element of the native content of a PDF page are PDF annotations. These are widgets that can be inserted at specified coordinates. Many different types of widgets are supported. They can be identified on the page, inserted, modified, and removed.

(pdf-page? obj) [procedure]

Returns `#t` if obj is an object representing a PDF page. Otherwise, `#f` is returned.

(make-pdf-page) [procedure]
(make-pdf-page box)
(make-pdf-page image)
(make-pdf-page image compress)
(make-pdf-page image compress rotate)
(make-pdf-page image compress rotate media)
(make-pdf-page image compress rotate media upscale)

Returns a new PDF page. If box is provided, it is either a size describing the size of the media box of the page, or a rectangle defining the media box of the page. Alternatively, an image can be provided as the basis for the new PDF page. In this case, parameters compress, rotate, media, and upscale can be provided to customize the usage of the image. compress is a flonum between 0.0 (= lowest quality) and 1.0 (= highest quality) defining the compression quality, rotate is a positive or negative multiple of 90 describing the rotation of the image, media is either `#f`, a size object, or a rect describing the media box of the page, and upscale is a boolean to enable the upscaling of the image if it is smaller than the size of the page.

(pdf-page-copy page) [procedure]

Returns a copy of the given PDF page.

(pdf-page-document page) [procedure]

Returns the PDF document to which the given PDF page belongs, or `#f` if the page has not been inserted into a PDF document.

(pdf-page-number page) [procedure]

Returns the page index (starting from 0) of the given PDF page in the PDF document in which it was inserted. `pdf-page-number` returns `#f` is the PDF page has not been inserted into a PDF document.

(pdf-page-label page) [procedure]

Returns the label of the given PDF page in the PDF document in which it was inserted. `pdf-page-label` returns `#f` is the PDF page has not been inserted into a PDF document or does not have a label.

(pdf-page-bounds page box-spec) [procedure]

Returns a rect describing the page bounds for the display box specifier box-spec of PDF page. box-spec is one of the following symbols: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`.

(pdf-page-bounds-set! page box-spec box) [procedure]

Sets the display box specified by box-spec for the given PDF page to the rect box. box-spec is one of the following symbols: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`.

(pdf-page-rotation page) [procedure]

Returns the rotation angle in degrees (a multiple of 90) of PDF page.

(pdf-page-rotation-set! page rotate) [procedure]

Sets the rotation angle of PDF_page_ to rotate. rotate is a positive or negative multiple of 90 describing the rotation of page.

(pdf-page-annotations-display page) [procedure]

Returns `#t` if annotations should be displayed on PDF page; otherwise `#f` is returned.

(pdf-page-annotations-display-set! page display?) [procedure]

Enables the display of annotations on PDF page if display is true. If display is `#f`, then the display of annotations gets disabled for page.

(pdf-page-annotations page) [procedure]

Returns a list of all PDF annotations on PDF page.

(pdf-page-annotation-ref page point) [procedure]

Returns the PDF annotations that can be found at coordinates point on PDF page. `#f` is returned if there is no annotation at point.

(pdf-page-annotation-add! page annot) [procedure]

Adds the PDF annotation annot to PDF page.

(pdf-page-annotation-remove! page annot) [procedure]

Removes the annotation annot from PDF page.

(pdf-page-underlay page) [procedure]

PDF pages are drawn in three layers: first an underlay drawing is drawn (if it exists) followed by the PDF page content including its annotations, and finally an overlay drawing is drawn (if it exists). `pdf-page-underlay` returns the underlay drawing for page if it exists, otherwise `#f` is returned.

(pdf-page-underlay-set! page drawing) [procedure]

Sets the underlay drawing of PDF page to drawing. An underlay drawing is removed if drawing is `#f`.

(pdf-page-overlay page) [procedure]

PDF pages are drawn in three layers: first an underlay drawing is drawn (if it exists) followed by the PDF page content including its annotations, and finally an overlay drawing is drawn (if it exists). `pdf-page-underlay` returns the overlay drawing for page if it exists, otherwise `#f` is returned.

(pdf-page-overlay-set! page drawing) [procedure]

Sets the overlay drawing of PDF page to drawing. An overlay drawing is removed if drawing is `#f`.

(pdf-page-images page) [procedure]

Returns a list of all images that can be found on PDF page.

(pdf-page-thumbnail page box size) [procedure]

Generates a thumbnail of size (in points) from the content in the rect box on PDF page and returns a corresponding image.

(pdf-page->bitmap page box size) [procedure]
(pdf-page->bitmap page box size ppi)
(pdf-page->bitmap page box size ppi ipol)

Returns a bitmap of size (in points) from the content in rect box on PDF page. ppi determines the number of pixels per inch. By default, ppi is set to 72. In this case, the number of pixels of the returned bitmap corresponds to the number of points (since 1 pixel corresponds to 1/72 of an inch). ipol is a fixnum between 0 and 4 indicating the interpolation quality used for creating the bitmap: `0` = default, `1` = none, `2` = low, `3` = high, and `4` = medium.

(pdf-page->string page) [procedure]

Returns a string representing all the text on PDF page. If no string can be extracted, `#f` is returned.

(pdf-page->styled-text page) [procedure]

Returns a styled-text object representing all the text on PDF page. If no styled-text can be extracted, `#f` is returned.

(pdf-page->bytevector page) [procedure]

Returns a bytevector representing a PDF document with page as the only page of the PDF document. If no binary representation of this page can be created, then `#f` is returned.

(draw-pdf-page page box-spec rect drawing) [procedure]

Draws the content within the display box specified by box-spec of PDF page into drawing. Drawings are defined by library `(lispkit draw)`. box-spec is one of the following symbols: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`. rect specifies a rectangular region into which page is drawn. rect can be specified in the following ways:

- `#f`: rect corresponds to the rectangular specified by box-spec.
- `#t`: rect has its origin at `zero-point` and the width and height correspond to the size of the rectangular specified by box-spec.
- `(x . y)`: rect has its origin at point (x, y) and the width and height correspond to the size of the rectangular specified by box-spec.
- `((x . y) . (w . h))`: rect corresponds to the given rectangular.
- `(#f . (w . h))`: rect_ has its origin at `zero-point` and the width and height correspond to `w` and `h` respectively.

## PDF outlines

A outline is an optional hierarchical component of a PDF document which defines the structure of a document and facilitates navigating within it. A PDF outline object represents a node in the outline hierarchy. Each outline object belongs at most to one PDF document. Except for outline objects representing the root of a document, all outline objects have a parent outline object. This root outline object is not visible to the reader of a PDF document and serves merely as a container for the visible outlines. Each outline object has an index which defines an ordering underneath the parent of the outline object. Outline objects have a customizable label, destination, and are associated with an optional action. Each outline object may have several children.

(pdf-outline? obj) [procedure]

Returns `#t` if obj is a PDF outline object; otherwise `#f` is returned.

(make-pdf-outline) [procedure]
(make-pdf-outline label)
(make-pdf-outline label page)
(make-pdf-outline label page point)
(make-pdf-outline label page point zoom)

Returns a new PDF outline object. label is a string defining the label of the outline object. page is a PDF page which is the target destination for this outline object. point is a specific point on that page and zoom is a floating-point number defining the zoom factor for that destination. All arguments are optional and `#f` by default.

(pdf-outline-document outline) [procedure]

If outline is the child of an outline object which is part of the outline hierarchy of a PDF document, then `pdf-outline-document` returns this PDF document.

(pdf-outline-parent outline) [procedure]

Returns the parent outline object of outline. For root outline objects, `pdf-outline-parent` returns `#f`.

(pdf-outline-index outline) [procedure]

Returns the index of outline within all the children sharing the same parent as outline. `pdf-outline-index` returns 0 for outline objects which do not have a parent.

(pdf-outline-label outline) [procedure]

Returns the label of outline if a label has been defined, or `#f` otherwise.

(pdf-outline-label-set! outline str) [procedure]

Sets the label of outline to string str.

(pdf-outline-destination outline) [procedure]

Returns the destination of outline. A destination is defined in terms of a list with three elements: (page point zoom). page is a PDF page which is the target destination for this outline object. point is a specific point on that page and zoom is a floating-point number defining the zoom factor for that destination. All elements can be `#f` if not defined.

(pdf-outline-destination-set! outline dest) [procedure]
(pdf-outline-destination-set! outline page)
(pdf-outline-destination-set! outline page point)
(pdf-outline-destination-set! outline page point zoom)

Sets the destination of outline. If dest is provided, it is either `#f` (in which case the destination will be removed), or a list with exactly three elements: (page point zoom). Alternatively, page, point, and zoom can be provided individually. page is a PDF page which is the target destination for this outline object. point is a specific point on that page and zoom is a floating-point number defining the zoom factor for that destination. point and zoom can be `#f` if not defined.

(pdf-outline-action outline) [procedure]

Returns the action associated with outline, or `#f` if no action is defined. The following action types are supported:

- (`goto` page point): Goes to point on page.
- (`goto-remote` url page-index point): Opens a PDF document at url and goes to point on the page with index page-index.
- (`goto-url` url): Opens the page/document at url.
- (`perform` action-name): Performs a named action. action-name is one of the following symbols: `none`, `find`, `go-back`, `go-forward`, `goto-page`, `first-page`, `last-page`, `next-page`, `previous-page`, `print`, `zoom-in`, or `zoom-out`.
- (`reset-fields` name …): Resets the fields with the names name …. name … are strings.
- (`reset-fields-except` name …): Resets all fields except for the ones with the names name …. name … are strings.

(pdf-outline-action-set! outline action) [procedure]

Sets the action of outline to action. action is a PDF outline action matching one of the following supported action types:

- (`goto` page point): Goes to point on page.
- (`goto-remote` url page-index point): Opens a PDF document at url and goes to point on the page with index page-index.
- (`goto-url` url): Opens the page/document at url.
- (`perform` action-name): Performs a named action. action-name is one of the following symbols: `none`, `find`, `go-back`, `go-forward`, `goto-page`, `first-page`, `last-page`, `next-page`, `previous-page`, `print`, `zoom-in`, or `zoom-out`.
- (`reset-fields` name …): Resets the fields with the names name …. name … are strings.
- (`reset-fields-except` name …): Resets all fields except for the ones with the names name …. name … are strings.

(pdf-outline-open? outline) [procedure]

Returns `#t` if the outline is currently open, otherwise `#f` is returned.

(pdf-outline-open-set! outline) [procedure]
(pdf-outline-open-set! outline open?)

Closes the outline if open? is `#t`, otherwise outline will be opened. If open? is not provided, outline’s open state will be toggled.

(pdf-outline-child-count outline) [procedure]

Returns the number of children of outline.

(pdf-outline-child-ref outline n) [procedure]

Returns the n-th child from outline. If that outline child does not exist, `#f` is returned.

(pdf-outline-child-insert! outline child) [procedure]
(pdf-outline-child-insert! outline n child)

Inserts a PDF outline object child at index n into outline. If n is not provided, child is inserted at the end.

(pdf-outline-child-remove! outline n) [procedure]

Removes the n-th child from outline. If there is no n-th child, then `pdf-outline-child-remove!` fails.

## PDF annotations

PDF annotations are non-intrusive elements added to a PDF document to provide comments, feedback, or interactive features without altering the original content. PDF annotations are represented via its own object by library `(lispkit pdf)`. There are a lot of different types of annotations, but only some are supported by this library. The type of an annotation is represented as a symbol. Supported are annotations of the following types: `circle`, `free-text`, `highlight`, `ink`, `line`, `link`, `popup`, `square`, `stamp`, `strike-out`, `text`, and `underline`.

(pdf-annotation? obj) [procedure]

Returns `#t` if obj is a PDF annotation object; otherwise `#f` is returned.

(make-pdf-annotation bounds type) [procedure]

Creates a new PDF annotation object with the given bounds and type. bounds is a rect that specifies the bounding box for the annotation. type is a symbol specifying the PDF annotation type. Supported are:

- `circle`: Displays an elliptical or circular shape on the page.
- `free-text`: Displays text directly on the page within a customizable box, remaining visible without needing to be opened. Callouts are a special type of free text annotation that includes a line or arrow pointing from the text box to a specific area of the document.
- `highlight`: Marks important text by applying a translucent color over it.
- `line`: Displays a single straight line on the page.
- `ink`: Allows for free-form drawing or sketching directly on the document, represented by a custom shape.
- `link`: Creates a clickable area that can jump to a web URL, a specific page within the document, or an external document.
- `popup`: Displays text in a pop-up window for entry and editing.
- `square`: Displays a rectangular shape on the page.
- `stamp`: Applies pre-defined or custom visual stamps (e.g., “Approved”, “Draft”, “Confidential”) to the document, similar to a physical rubber stamp.
- `strike-out`: Draws a line through selected text, often indicating it should be removed.
- `text`: A sticky-note like annotation which adds a small pop-up note or comment icon to the page that opens to display text when clicked.
- `underline`: Draws a line beneath selected text.
- `widget`: Displays interactive form elements, including text or signature fields, radio buttons, checkboxes, push buttons, pop-ups, and tables.

Annotations of other types can be managed with `(lispkit pdf)`, but there is no specific support to create or modify them. They typically use symbolic identifiers that start with a capital letter.

Once created, some annotations might require other attributes/metadata to be set. This can be done with the various PDF annotation management procedures.

Annotations created with `make-pdf-annotation` are by default not attached to a PDF page. Adding an annotation to a PDF page can be done with procedure `pdf-page-annotation-add!`.

(pdf-annotation-page annot) [procedure]

Returns the PDF page on which this annotation is shown. If this annotation is not associated with a PDF page, `#f` is returned.

(pdf-annotation-type annot) [procedure]

Returns a symbol representing the annotation type of annot. The officially supported annotation types are `circle`, `free-text`, `highlight`, `ink`, `line`, `link`, `popup`, `square`, `stamp`, `strike-out`, `text`, `underline`, and `widget`.

(pdf-annotation-name annot) [procedure]

Returns the name of PDF annotation annot as a string. If annot does not have a name, `#f` is returned.

(pdf-annotation-name-set! annot str) [procedure]

Sets the name of PDF annotation annot to string str. If str is `#f`, then the name of annot is cleared.

(pdf-annotation-bounds annot) [procedure]

Returns the bounds of PDF annotation annot as a rect.

(pdf-annotation-bounds-set! annot bounds) [procedure]

Sets the bounds of PDF annotation annot to rect bounds.

(pdf-annotation-padding annot) [procedure]

Returns the padding of PDF annotation annot as a list with four elements: `(left-padding top-padding right-padding bottom-padding)`.

(pdf-annotation-padding-set! annot padding) [procedure]

Sets the padding of PDF annotation annot to padding. padding is a list of four flonum values: `(left-padding top-padding right-padding bottom-padding)`. If padding is `#f`, padding is removed from annot.

(pdf-annotation-border annot) [procedure]

Returns the border of PDF annotation annot. If annot does not have a border, `#f` is returned. The border is expressed either as a list of two elements `(border-type line-width)` or three elements `(border-type line-width dash-pattern)` for dashed borders. The supported border types are `solid`, `dashed`, `beveled`, `inset`, and `underline`. The line width is a flonum value in points. The dash pattern is a list of flonum values that specify the lengths (measured in points) of the line segments and gaps in the pattern. The values in the array alternate, starting with the first line segment length, followed by the first gap length.

(pdf-annotation-border-set! annot border) [procedure]

Sets the border of the PDF annotation annot to border. border is either a list of two elements `(border-type line-width)` or three elements `(border-type line-width dash-pattern)` for dashed borders. The supported border types are `solid`, `dashed`, `beveled`, `inset`, and `underline`. The line width is a flonum value in points. The dash pattern is a list of flonum values that specify the lengths (measured in points) of the line segments and gaps in the pattern. The values in the array alternate, starting with the first line segment length, followed by the first gap length. border may also be `#f`, in which case the border of annot is cleared.

(pdf-annotation-contents annot) [procedure]

Returns a string representing the textual content associated with the PDF annotation annot. `#f` is returned if there is no textual content associated with annot.

(pdf-annotation-contents-set! annot str) [procedure]

Sets the textual content of PDF annotation annot to string str. If str is `#f`, the existing textual content associated with annot is cleared.

(pdf-annotation-alignment annot) [procedure]

Returns a symbol representing the textual alignment used by PDF annotation annot. Supported alignment values are `left`, `right`, `center`, `justified`, and `natural`.

(pdf-annotation-alignment-set! annot alignment) [procedure]

Sets the textual alignment used by PDF annotation annot to alignment. alignment is one of the following symbols: `left`, `right`, `center`, `justified`, and `natural`.

(pdf-annotation-text-intent annot) [procedure]

Returns the text intent associated with PDF annotation annot as a symbol (for the supported intents) or string (for the unsupported ones). The two supported intents are `callout` and `type-writer`.

(pdf-annotation-text-intent-set! annot intent) [procedure]

Sets the text intent associated with PDF annotation annot to intent. intent is either a string, or one of the two supported symbols `callout` and `type-writer`. If intent is `#f`, the text intent is cleared.

(pdf-annotation-font annot) [procedure]

Returns the font associated with PDF annotation annot. If no font is associated with annot, `#f` is returned.

(pdf-annotation-font-set! annot font) [procedure]

Associates font with PDF annotation annot. font is a font object as defined by library `(lispkit draw)`.

(pdf-annotation-color annot) [procedure]

Returns the annotation color of PDF annotation annot.

(pdf-annotation-color-set! annot color) [procedure]

Sets the annotation color of PDF annotation annot to color. color is a color object as defined by library `(lispkit draw)`.

(pdf-annotation-interior-color annot) [procedure]

Returns the interior color of PDF annotation annot.

(pdf-annotation-interior-color-set! annot color) [procedure]

Sets the interior color of PDF annotation annot to color. color is a color object as defined by library `(lispkit draw)`.

(pdf-annotation-background-color annot) [procedure]

Returns the background color of PDF annotation annot.

(pdf-annotation-background-color-set! annot color) [procedure]

Sets the background color of PDF annotation annot to color. color is a color object as defined by library `(lispkit draw)`.

(pdf-annotation-font-color annot) [procedure]

Returns the font color of PDF annotation annot.

(pdf-annotation-font-color-set! annot color) [procedure]

Sets the font color of PDF annotation annot to color. color is a color object as defined by library `(lispkit draw)`.

(pdf-annotation-start-point annot) [procedure]

Returns a pair consisting of the point where a line begins, in annotation-space coordinates, and a symbol specifying the start line style. Supported line styles are `none`, `square`, `circle`, `diamond`, `open-arrow`, `closed-arrow`. Custom line styles are represented as strings.

(pdf-annotation-start-point-set! annot point) [procedure]
(pdf-annotation-start-point-set! annot style)
(pdf-annotation-start-point-set! annot point style)

Sets the starting point of a line represented by PDF annotation annot to point and the corresponding start line style to style. Supported line styles are `none`, `square`, `circle`, `diamond`, `open-arrow`, `closed-arrow`. Custom line styles are represented as strings.

(pdf-annotation-end-point annot) [procedure]

Returns a pair consisting of the point where a line ends, in annotation-space coordinates, and a symbol specifying the end line style. Supported line styles are `none`, `square`, `circle`, `diamond`, `open-arrow`, `closed-arrow`. Custom line styles are represented as strings.

(pdf-annotation-end-point-set! annot point) [procedure]
(pdf-annotation-end-point-set! annot style)
(pdf-annotation-end-point-set! annot point style)

Sets the end point of a line represented by PDF annotation annot to point and the corresponding end line style to style. Supported line styles are `none`, `square`, `circle`, `diamond`, `open-arrow`, `closed-arrow`. Custom line styles are represented as strings.

(pdf-annotation-icon annot) [procedure]

Returns the type of icon to display for a pop-up text annotation represented by PDF annotation annot as a symbol. Supported icon types are `comment`, `key`, `note`, `help`, `new-paragraph`, `paragraph`, and `insert`.

(pdf-annotation-icon-set! annot icon) [procedure]

Sets the icon type for PDF annotation annot to icon. icon is one of the following supported icon types: `comment`, `key`, `note`, `help`, `new-paragraph`, `paragraph`, and `insert`. The icon type is only relevant for pop-up text annotations.

(pdf-annotation-stamp annot) [procedure]

Returns the stamp string associated with PDF annotation annot. If there is no stamp associated with annot, `#f` is returned.

(pdf-annotation-stamp-set! annot stamp) [procedure]

Sets the stamp of PDF annotation annot to stamp. stamp is a string or `#f` if no stamp should be associated.

(pdf-annotation-popup annot) [procedure]

Returns a pair consisting of a PDF popup annotation and a boolean value indicating whether the popup annotation is open (`#t`) or not (`#f`). If no popup annotation is associated with PDF annotation annot, then `#f` is returned.

(pdf-annotation-popup-set! annot popup) [procedure]
(pdf-annotation-popup-set! annot popup)
(pdf-annotation-popup-set! annot popannot open)

Associates a popup annotation with PDF annotation annot. popup is either a PDF annotation, or it is a pair consisting of a PDF annotation and a boolean value indicating whether the popup annotation is open (`#t`) or not (`#f`). If two arguments are provided, popannot refers to a PDF annotation and boolean open to its open status. If popannot is `()`, then the current PDF popup annotation remains as is. If popannot is `#f`, it is being removed.

(pdf-annotation-markup-type annot) [procedure]

Returns the markup type of PDF annotation annot. The markup type is either `highlight`, `strike-out`, `underline`, `redact`, or `#f` if no markup type is defined.

(pdf-annotation-markup-type-set! annot type) [procedure]

Sets the markup type of PDF annotation annot to type. type is either `#f` (for no markup type) or one of the following symbols: `highlight`, `strike-out`, `underline`, or `redact`.

(pdf-annotation-markup-points annot) [procedure]

Returns the quadrilateral points that define the marked text region, or `#f` if no text is marked up by PDF annotation annot. The quadrilateral points are returned as a list of points bounding the marked-up text.

(pdf-annotation-markup-points-set! annot points) [procedure]

Sets the quadrilateral points that define the text region marked-up by PDF annotation annot to points. points is a list of points or `#f`, which will remove existing quadrilateral points.

(pdf-annotation-callout-points annot) [procedure]

Returns the callout points associated with callout annotation annot. A callout annotation includes a text box and an arrow that can be moved independently of the text box. The arrow consists of an optional knee line followed by an end-point line defined by 2 or 3 points. These are returned by `pdf-annotation-callout-points` as a list of 2 or 3 points. `#f` is returned if there are no callout points.

(pdf-annotation-callout-points-set! annot copts) [procedure]

Sets the callout points of callout annotation annot to copts. A callout annotation includes a text box and an arrow that can be moved independently of the text box. The arrow consists of an optional knee line followed by an end-point line defined by 2 or 3 points. copts is either a 2 or 3 point list. Alternatively, copts can be set to `#f`, in which case potentially existing callout points are being removed.

(pdf-annotation-shapes annot) [procedure]

Returns a list of shape objects that compose the PDF annotation annot. Shape objects are defined by library `(lispkit draw)`. They are provided in annotation-space coordinates.

(pdf-annotation-shape-add! annot sh) [procedure]

Adds a shape object sh to the list of shape objects that compose the PDF annotation annot. Shape objects are defined by library `(lispkit draw)`. They are provided in annotation-space coordinates.

(pdf-annotation-shapes-clear! annot) [procedure]

Removes all shape objects from the PDF annotation annot. Shape objects are defined by library `(lispkit draw)`. They define the overall shape of a PDF annotation.

(pdf-annotation-modification-date annot) [procedure]

Returns the modification date of PDF annotation annot as a date-time object as defined by library `(lispkit date-time)`.

(pdf-annotation-modification-date-set! annot dt) [procedure]

Sets the modification date of PDF annotation annot to dt. dt is a date-time object as defined by library `(lispkit date-time)`.

(pdf-annotation-username annot) [procedure]

Returns the username associated with PDF annotation annot as a string or `#f` if there is no associated username.

(pdf-annotation-username-set! annot name) [procedure]

Sets the username associated with PDF annotation annot to name. name is either a string or it is `#f`, in which case a potentially existing username is being removed.

(pdf-annotation-url annot) [procedure]

Returns the URL associated with PDF annotation annot as a string. `#f` is returned if there is no associated URL.

(pdf-annotation-url-set! annot url) [procedure]

Sets the URL associated with PDF annotation annot to url. url is either a string or it is `#f`, in which case a potentially existing URL is being removed.

(pdf-annotation-destination annot) [procedure]

Returns the document destination for link annotation annot. A destination is defined in terms of a list with three elements: (page point zoom). page is a PDF page which is the target destination for this outline object. point is a specific point on that page and zoom is a floating-point number defining the zoom factor for that destination. All elements can be `#f` if not defined.

(pdf-annotation-destination-set! annot dest) [procedure]
(pdf-annotation-destination-set! annot page)
(pdf-annotation-destination-set! annot page point)
(pdf-annotation-destination-set! annot page point zoom)

Sets the document destination for link annotation annot . If dest is provided, it is either `#f` (which will remove the destination), or a list with exactly three elements: (page point zoom). Alternatively, page, point, and zoom can be provided individually. page is a PDF page which is the target destination for this outline object. point is a specific point on that page and zoom is a floating-point number defining the zoom factor for that destination. point and zoom can be `#f` if not defined.

(pdf-annotation-action annot) [procedure]

Returns the action associated with PDF annotation annot, or `#f` if no action is defined. The following forms of actions are supported:

- (`goto` page point): Goes to point on page.
- (`goto-remote` url page-index point): Opens a PDF document at url and goes to point on the page with index page-index.
- (`goto-url` url): Opens the page/document at url.
- (`perform` action-name): Performs a named action. action-name is one of the following symbols: `none`, `find`, `go-back`, `go-forward`, `goto-page`, `first-page`, `last-page`, `next-page`, `previous-page`, `print`, `zoom-in`, or `zoom-out`.
- (`reset-fields` name …): Resets the fields with the names name …. name … are strings.
- (`reset-fields-except` name …): Resets all fields except for the ones with the names name …. name … are strings.

(pdf-annotation-action-set! annot action) [procedure]

Sets the action of PDF annotation annot to action. action is a PDF action matching one of the following supported forms of actions:

- (`goto` page point): Goes to point on page.
- (`goto-remote` url page-index point): Opens a PDF document at url and goes to point on the page with index page-index.
- (`goto-url` url): Opens the page/document at url.
- (`perform` action-name): Performs a named action. action-name is one of the following symbols: `none`, `find`, `go-back`, `go-forward`, `goto-page`, `first-page`, `last-page`, `next-page`, `previous-page`, `print`, `zoom-in`, or `zoom-out`.
- (`reset-fields` name …): Resets the fields with the names name …. name … are strings.
- (`reset-fields-except` name …): Resets all fields except for the ones with the names name …. name … are strings.

(pdf-annotation-display annot) [procedure]

Returns a boolean value indicating whether the PDF annotation annot should be displayed.

(pdf-annotation-display-set! annot disp?) [procedure]

Controls whether the PDF annotation annot should be displayed. If disp? is `#f`, the annotation will be hidden, otherwise shown.

(pdf-annotation-print annot) [procedure]

Returns a boolean value indicating whether the PDF annotation annot should appear when the document is printed.

(pdf-annotation-print-set! annot print?) [procedure]

Controls whether the PDF annotation annot should be printed. If print? is `#f`, the annotation will be hidden while printing, otherwise shown.

(pdf-annotation-highlighted annot) [procedure]

Returns a boolean value indicating whether the PDF annotation annot is in a highlighted state, such as when the mouse is down on a link annotation.

(pdf-annotation-highlighted-set! annot highl?) [procedure]

Controls whether the PDF annotation annot should be put into a highlighted state, such as when the mouse is down on a link annotation. If highl? is `#f`, the annotation will not be in highlighted state, otherwise it will.

(pdf-annotation-attributes annot) [procedure]

Returns the attribute dictionary of the PDF annotation annot as an association list mapping symbols to attribute values.

(pdf-annotation-attributes-ref annot attrib) [procedure]

Returns the attribute value for the given attribute key attrib (a symbol) from the dictionary of the PDF annotation annot. `#f` is returned if attribute attrib does not exist.

(pdf-annotation-attributes-set! annot attrib val) [procedure]

Sets the attribute given by symbol attrib to the attribute value val for the dictionary of the PDF annotation annot.

(pdf-annotation-attributes-remove! annot attrib) [procedure]

Removes the attribute identified by symbol attrib from the dictionary of the PDF annotation annot.

(draw-pdf-annotation annot box-spec rect drawing) [procedure]

Draws the PDF annotation annot within the display box specified by box-spec into drawing. Drawings are defined by library `(lispkit draw)`. box-spec is one of the following symbols: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`. rect specifies a rectangular region into which page is drawn. rect is a rectangle specified by an expression of this form: `((x . y) . (w . h))`.

## Paper sizes

letter-size [object]
legal-size
executive-size
a2-size
a3-size
a4-size
a5-size
a6-size
b3-size
b4-size
b5-size
b6-size
c3-size
c4-size
c5-size
c6-size

A size object representing a corresponding standardize size of a page in points. The size object is assuming 72 ppi, i.e. that there are 72 points per inch.

    ;; US sizes
    letter-size    ⇒  (612.0 . 792.0)  ; 8.5" × 11"
    legal-size     ⇒  (612.0 . 1008.0) ; 8.5" × 14"
    executive-size ⇒  (522.0 . 756.0)  ; 7.25" × 10.5"

    ;; ISO sizes
    a2-size        ⇒  (1190.4 . 1683.6)
    a3-size        ⇒  (841.8 . 1190.4)
    a4-size        ⇒  (595.2 . 841.8)
    a5-size        ⇒  (419.4 . 595.2)
    a6-size        ⇒  (297.6 . 419.4)