The Shapes a Page Lays over What It Draws

Summary

Some marks belong over a page rather than in it: the circle around a clause, the line that ties a comment to a figure, the outline drawn around an area of a plan. Reading software shows them over the page, lists them beside it, and can be told to keep them off the paper. Each carries a note that reading software shows when a mouse rests on it.

Request Schema

• page_review_marks — array, optional, empty by default.
• page_review_marks[].page — integer ≥ 1, required. The page the shapes are for.
• page_review_marks[].shapes — array, required. The shapes that page carries, in the order they are written.
• shapes[].type — string, required. One of square, circle, line, polygon, polyline, redaction, text_mark, caret, ink, sticky_note, file_attachment, free_text, stamp.
• square and circle — llx, lly, urx, ury: numbers, all required, the rectangle the shape is inscribed in. interior — colour, optional, what fills it. effect — plain or cloudy, optional, how the border is drawn.
• line — x1, y1, x2, y2: numbers, all required. endings — object, optional, what each end carries, under from and to, each one of none (nothing drawn, which is what an end left out carries), square, circle, diamond, open_arrow, closed_arrow, butt, reverse_open_arrow, reverse_closed_arrow or slash. interior — colour, optional, what fills those endings.
• polygon and polyline — vertices: array of two-number pairs, required. interior — colour, optional. polygon also takes effect, polyline also takes endings.
• redaction — llx, lly, urx, ury: numbers, all required, the part marked. over — array, optional, the patches inside it, each four corners counterclockwise; absent marks the rectangle itself. fill — colour, optional, what the emptied patch is filled with. overlay_text — string, optional, the words printed where the content was. repeating — boolean, optional, false by default, whether those words are set again and again until the patch is full. aligned — one of left (the default), center and right, where those words sit; read only beside words.
• A redaction states what must go. It does not take it out. What fill, overlay_text and aligned describe is the page as it will be once reading software has applied the mark and written the document out again: until that happens the words are still in the file under the mark, and a search finds them.
• text_mark — style: one of highlight, underline, strike_out and squiggly, required. over — array, required, the passage: one patch per line it runs across, each four corners counterclockwise; an empty one is refused. A highlight is painted in its color, which it must state, multiplied with the page so the letters under it stay legible; the other three are stroked in theirs, black where they state none.
• caret — llx, lly, urx, ury: numbers, all required, the box the caret stands in, filled in its color. inset — four numbers, optional, how far it is drawn in from the left, bottom, right and top edges. paragraph — boolean, optional, false by default, whether the insertion is a new paragraph.
• ink — strokes: array, required, the strokes of a scribble drawn freehand, each an array of two-number points in the order the pen went through them, at least two to a stroke.
• sticky_note — x, y: numbers, required, the lower-left corner of its icon, twenty points on a side. icon — one of note (the default), comment, key, help, new_paragraph, paragraph and insert. open — boolean, optional, false by default, whether its words show open when the document is opened. Its contents are required: they are the words it opens on.
• file_attachment — x, y: numbers, required, the lower-left corner of its icon, twenty points on a side. file — string, required, the name of one of the request's attachments, which the icon opens. icon — one of push_pin (the default), graph, paperclip and tag.
• free_text — llx, lly, urx, ury: numbers, all required, the box. text — string, required, the words laid in it, which are also its contents unless it states other ones; a box that does not hold every line of them is refused. style — object, required, how they are set: the font, font_size, color, align and indents of a flowed text item, its colour given in numbers. callout — object, optional, the line pointing the box at a spot of the page: line, two or three points, the spot first, and ending, one of a line's endings, drawn at the spot. typewriter — boolean, optional, false by default, whether the words are typed straight onto the page, with no frame; never beside callout.
• stamp — llx, lly, urx, ury: numbers, all required, the box it claims. words — object, optional, the line pressed across the box: the content, font, span, slant, color and shadow of a stamp item; absent shows the frame of the box. icon — optional, which of the standard's stamps it stands for: approved, experimental, not_approved, as_is, expired, not_for_public_release, confidential, final, sold, departmental, for_comment, top_secret, draft or for_public_release.
• Common to every shape: contents — string, optional, the note reading software shows. name — string, optional, what the shape is known by. color — colour, optional, the border's own. border — object, optional, width in points and an optional dash. layer — string, optional, the declared layer the shape is drawn on.
• shapes[].flags — object, optional. printed — boolean, whether the shape goes on paper. hidden, no_view, no_zoom, no_rotate, invisible, read_only — booleans, false by default.
• shapes[].appearance — array, optional. The shapes the mark is drawn with, in place of the ones built from what it states: the articles a named drawing holds — path, rect, line — in the page's own coordinates. Nothing is checked against what the mark states. They hold no text and paint in colours given in numbers: a gradient, a repeating cell, a declared colour space or a graphics state is refused.
• overlay — array, optional, on a redaction. The shapes the emptied patch is drawn with once the mark is applied: the same articles under the same rule, measured from the lower-left corner of its rectangle rather than from the page's.
• shapes[].flags also takes locked, which bars moving, resizing and deleting the mark while leaving its note free to change; locked_contents, which bars changing its note while leaving it free to move; and toggle_no_view, which turns no_view around while the pointer is over the mark or while it is selected. All three are booleans, false by default.
• A sticky note's icon also takes cross_hairs, right_arrow, right_pointer, up_arrow and up_left_arrow. A note setting a state — marked or unmarked, or accepted, rejected, cancelled or completed — sets the shape its in_reply_to names to that state. Every shape also takes rich_contents, its words as the body of an XHTML document; opacity, from 0 to 1; grouped_with, the name of the shape heading the group it joins; and popup, {"llx", "lly", "urx", "ury", "open"}, the window reading software shows its words in.

A shape is laid over the page, not into what the page draws: it is kept out of the text a reader copies, and out of the structure a document states about itself.