A drawing made once, shown by a button

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

A button you click on says more with a small drawing on it than with a word: a green tick, an arrow, a cross. You draw that small motif once, give it a name, and the button carries it. The drawing is made of lines and shapes described one by one, which keeps it crisp at any size: it is worked out, not photographed.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

drawings declares the drawings the document defines for itself, each under the name a button's icon shows it by. A drawing carries the same articles a page does — a path, a rectangle, a line, a block of text — laid out in a space of its own rather than on a sheet. Nothing fresh is invented there: they are the articles the schema already has. Placing a drawing on a page is planned for a future version; today, its use is a button's icon.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

• drawings — array, optional, empty by default.
• drawings[].name — string, required. The name an icon shows it by. A name declared twice keeps the last.
• drawings[].box — object, required. The part of the drawing's space that is kept: x, y, width, height, numbers, all required. Nothing outside it is drawn.
• drawings[].items — array, required. The shapes it is made of, in drawing order. Four kinds: path, rect, line, text.
• drawings[].matrix — array of six numbers, optional. What the drawing's own space is worth in the space it is shown in. Absent, it is shown as it was drawn.
• A drawing article declaring pages, layer, id or relative_to is refused: a drawing is not on a page, and its coordinates name no page variable.
• An image and a code are planned for a future version inside a drawing: a drawing has no access to the request's images.
• The button showing it is a push_button item, through its icon, rollover_icon or down_icon key, with icon_fit for the framing and layout for where the caption sits.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "drawings": [
    {
      "name": "tick",
      "box": { "x": 0, "y": 0, "width": 20, "height": 20 },
      "items": [
        {
          "type": "line",
          "from": { "x": 3, "y": 10 },
          "to": { "x": 8, "y": 4 },
          "stroke": { "width": 2, "color": [0.09, 0.42, 0.24] }
        },
        {
          "type": "line",
          "from": { "x": 8, "y": 4 },
          "to": { "x": 17, "y": 16 },
          "stroke": { "width": 2, "color": [0.09, 0.42, 0.24] }
        }
      ]
    }
  ],
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "push_button",
      "name": "approve",
      "rect": { "llx": 60, "lly": 740, "urx": 84, "ury": 764 },
      "font": "sans",
      "font_size": 10,
      "icon": "tick",
      "layout": "icon_only"
    }
  ]
}

The line that sends it, in three languages

Glossary

request

One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.

layer

A named group of things drawn on a page that a reader can switch on and off, like tracing paper laid over a plan. A drawing can hold its measurements on one and its notes on another, and a layer can be set to show on screen and stay off the printer.

Every word the site explains