Drawing
=======

You can draw all kinds of things in buttons.

you make a list of drawing primitives, whose values you can change



In the interests of quick display, drawing is organized to reflect the low-level drawing primitives.

.. data:: color 

   A **color** specification is a scalar, or an array of one to four scalars.
      | f or {f}: sets all three colors to *f* on a scale of 0 to 1.
      | {f, alpha}: sets all three colors to *f* with opaqueness *alpha*
      | {r, g, b}: sets colors to *red*, *green*, and *blue*
      | {r, g, b, alpha}: sets colors to *red*, *green*, and *blue*, with opaqueness *alpha*

.. data:: drawElem

   Every call to draw returns a *drawElem*, which can be used as an argument to setDrawElement.  For the curious, it contains
      | *drawElem.type* is the command from the draw() call that did it.
      | *drawElem.vector* is the array of floats used by low-level rendering
      | *drawElem.uie* is the UIE (a button) in which the drawing is done
      | *drawElem.flags* encodes characteristics of this drawElem 


.. function:: setDrawElement(drawElem, command [, args...])

   * **setDrawElement** (*drawElem*, "origin", x, y) : adjust x and y coordinates of *drawElem*
   * **setDrawElement** (*drawElem*, "size", width, height) : adjust size of rects and ovals
   * **setDrawElement** (*drawElem*, "color", color) : change color of *drawElem*

.. function:: draw(b, command [, args...])


.. function:: plot(b, command [, args...]) *deprecated*

   Add to graphics list in button *b*.  Return a :data:`drawElem`.

   * **draw** (*b*, "clear") : clear all drawing in *b* and return NULL
   * **draw** (*b*, "move", *x*, *y*) : set drawing point to *x*, *y*
   * **draw** (*b*, "line", *x*, *y*) : draw line from drawing point to *x*, *y*
   * **draw** (*b*, "relativeMove", *x*, *y*) :
     move drawing point in direction *x*, *y*

        | more remarks
        | and yet more

   * **draw** (*b*, "relativeLine", *x*, *y*) :
     draw line from drawing point in direction *x*, *y*
   * **draw** (*b*, "closePath") : see drawing complicated stuff
   * **draw** (*b*, "stroke") : see drawing complicated stuff
   * **draw** (*b*, "fill") : see drawing complicated stuff
   * **draw** (*b*, "lineWidth", *w*) : set stroke line width to *w* 
   * **draw** (*b*, "color", *colorArray*) : set stroke color to :data:`color` *colorArray*.
   * **draw** (*b*, "oval", *x*, *y*, *width*, *height*) :
     draw oval of *width* and *height* centered on *x*, *y*
   * **draw** (*b*, "rect", *x*, *y*, *width*, *height*) :
     draw rect of *width* and *height* centered on *x*, *y* 
   * **draw** (*b*, "curve", *x*, *y*, *cx1*, *cy1*, *cx2*, *cy2*) :
     draw a Bezier curve from drawing point to *x*, *y*
     with control points *cx1*, *cy1* and *cx2*, *cy2*
   * **draw** (*b*, "relativeCurve", *x*, *y*, *cx1*, *cy1*, *cx2*, *cy2*) :
     draw a Bezier curve from drawing point in the direction *x*, *y*
     with control points *cx1*, *cy1* and *cx2*, *cy2*

   * **draw** (*b*, "moveP", *x*, *y*) : same as "move" but in pixels
   * **draw** (*b*, "lineP", *x*, *y*) : same as "line" but in pixels
   * **draw** (*b*, "relativeMoveP", *x*, *y*) : same as "relativeMove" but in pixels
   * **draw** (*b*, "relativeLineP", *x*, *y*) : same as "relativeLine" but in pixels
   * **draw** (*b*, "ovalP", *x*, *y*, *width*, *height*) : same as "oval" but in pixels
   * **draw** (*b*, "rectP", *x*, *y*, *width*, *height*) : same as "rect" but in pixels
   * **draw** (*b*, "curveP", *x*, *y*, *cx1*, *cy1*, *cx2*, *cy2*) :
     same as "curve" but in pixels
   * **draw** (*b*, "relativeCurveP", *x*, *y*, *cx1*, *cy1*, *cx2*, *cy2*) :
     same as "relativeCurve" but in pixels

   Draw a marker of size *size* at drawing point.  Drawing point is unchanged

   * **draw** (*b*, "marker", *x*, *y*, *size*, *m*) : *x* and *y* between 0 and 1, *m* is one of:

     .. hlist::  :columns: 1

        * **o**: Circle
        * **+**: Plus sign
        * *****: Asterisk
        * **.**: Point
        * **x**: Cross
        * **s**: Square
        * **d**: Diamond
        * **^**: Upward-pointing triangle
        * **v**: Downward-pointing triangle
        * **>**: Right-pointing triangle
        * **<**: Left-pointing triangle
        * **p**: Five-pointed star (pentagram)
        * **h**: Six-pointed star (hexagram)