## proc drawcommands

Version 2.32
Scripts

Manual page for proc_drawcommands(PL)

drawcom

proc drawcommands reads and executes sets of commands which specify low-level drawing operations.``

The commands may be one of two distinct types:

- a ploticus drawdump file - a file that has been created previously by running `pl -drawdump` or `pl -drawdumpa` .`` Often used with prefabs as a a convenient way to overlay or combine graphs.``
- ploticus draw commands - a command language described below for creating lines, polygons, and text, in either absolute space or scaled space. May be useful as a flexible way to add annotation, or to add graphics that the other plotting procedures cannot produce, or to import graphics generated programatically.``

If you use the `dumpfile` attribute, drawdump content is expected. Otherwise, ploticus draw commands are expected.``

See also the draw prefab which provides a convenient command line interface for processing drawdump files or drawcommands.``

## Attributes

dumpfile filename

  A file containing a drawdump (as generated using `pl -drawdump` or `pl -drawdumpa`).``

  Security concern: user-supplied values (such as CGI variables) should not be used to build the filename, unless proper measures are taken to detect and remove the `../` construct (used as a hack to see higher levels of the file system).``

commands multiline-text

  A list of one or more ploticus draw commands (see below). One command per line.`` Ends with a blank line.``

file filename

  A file containing ploticus draw commands (see below). May be `stdin` to read draw commands from standard input.``

  Security concern: user-supplied values (such as CGI variables) should not be used to build the filename, unless proper measures are taken to detect and remove the `../` construct (used as a hack to see higher levels of the file system).``

## Example of draw commands

For a quick tutorial on draw commands, see below.``

     #proc drawcommands
    commands:
      color blue
      linetype 0 2 1
      mov 1 1
      lin 1 2
      lin 2 2
      lin 1 1

A Gallery example where proc drawcommands is used is drawcom

## The draw command set

Here is a summary of the draw command set.`` The commands are interpreted, and should be given one per line.`` Quoting is never used for string literals. Note that proc drawcommands have nothing to do with proc getdata or the "current data set".`` For an explanation of absolute units and scaled units, see scaleunits.``

Command | Description
.``

  mov x y | = move to (x,y) in absolute units

  lin x y | = line to (x,y) in absolute units

  path x y | = extend current polygon fill path to (x,y) in absolute units (see also `fill` below).``

  movs, lins, paths | = same as above but for scaled units (assumes proc areadef has already been used to set up a scaled space).``

  movp, linp, pathp | = same as above but operands may be in either absolute space or scaled space. If an operand ends with `(s)` it is assumed to be in scaled space; otherwise it is assumed to be in absolute space.``

  text s | = display text string s left adjusted at current location. s should not be enclosed in quotes.``

  centext s | = display text string s centered around current location s should not be enclosed in quotes.``

  rightjust s | = display text string s right-aligned to current location s should not be enclosed in quotes.``

  cblock x1 y1 x2 y2 color outline | = display a colored rectangle. The lower left is at (x1,y1) in absolute units; upper right is at (x2,y2) in absolute units; color is the color; outline is 1 to produce an outline, 0 not.``

  fill | = close and fill the polygon path with the current color.``

  mark x y sym r | = produce a symbol at (x,y).`` sym is a graphcore data point symbol code as described in symboldetails.`` r is the radius in absolute units.``

  color c | = set the current color to c

  textsize p

  = set the current text size to p points
  linetype style width dashscale | = set the current line details.``

  clr | = clear the display

  backcolor c | = set the current background color to c

## How to use draw commands

Suppose you have an imaginary pen,

`color blue` sets the pen color to blue
`mov x1 y1` would move the "pen" to x1,y1 in inches from lower left corner
`lin x2 y2` would lower the "pen" and then draw a line to x2,y2
`lin x3 y3` would continue the line to x3,y3

If you don't want to use inches, you can set up a plotting area with whatever xrange and yrange you want. Then..``
`movs x1 y1` would move the pen to x1,y1 relative to xrange and yrange
`lins x2 y2` would lower the pen and then draw a line to x2,y2
`lins x3 y3` would continue the line to x3,y3

This is fine for drawing lines, but what about filled shapes?`` To do shapes, you do the same thing as above, but use `path` instead of `lin`, or `paths` instead of `lins`. When you have drawn one shape, you fill it in using:
`fill red`

Then you can begin the next shape.``
data display engine
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` August 23, 2005.