PyGUI - class Canvas

# class `Canvas`

Canvas is an abstract class representing something that can be drawn upon. It may represent an area of the screen, an offscreen pixmap, or something else such as a printed page.

The drawing model of a Canvas is based on a subset of the PostScript or PDF drawing model. In this model, drawing is performed by first building up a geometric description of a path, and then stroking or filling the path with a specified color. Paths can also be used to define a clipping region to which subsequent drawing is restricted.

## Graphics state

Each canvas maintains a graphics state consisting of the following items:

- A current color for drawing operations.
- A current pen size for stroking and framing operations.
- A current font for drawing text.
- A current point used in path construction and text drawing.
- A clipping region to which all drawing operations are restricted.

The canvas also maintains a graphics state stack. The current graphics state can be pushed onto the stack using the `gsave` method, and popped from the stack using the `grestore` method.

## Current path

Each canvas has a current path. The current path consists of a collection of path segments, each of which consists of a sequence of points connected by straight lines. Each path segment can be either open or closed. Some operations expect closed path segments, in which case an open segment is treated as though it were closed by a line connecting its last point to its first point.
Paths are constructed using the `newpath`, `moveto`, `lineto`, `rmoveto`, `rlineto` and `closepath` methods. Once constructed, a path can be used in the following ways:

- It can be stroked with the current pen and color using the `stroke` method.
- It can be filled with the current color using the `fill` method.
- It can be used to modify the current clipping region using the `clip` method.

Note that, unlike the PostScript imaging model, the current path is not considered part of the graphics state and is not affected by `gsave` and `grestore` operations.
Also unlike PostScript, the current path is not cleared by stroking and filling operations. The only method which clears the current path is `newpath`.

## Drawing text

Text is drawn using the `show_text` method, which draws a string in the current font and color starting at the current point. The current point is then advanced to the end of the string, ready for drawing another string.

## Higher-level drawing operations

In addition to the primitive operations making up the drawing model, there are a number of higher-level drawing methods which provide more convenient ways of drawing commonly-used shapes. They also provide the only means currently implemented for drawing curved shapes.

## Properties

`forecolor`
  Color to be used for solid filling, stroking and framing operations.
`backcolor`
  Color to be used for erasing operations [which are not yet implemented].

`pensize`
  Width of the pen used for stroking paths and framing shapes.

`font`
  Font to be used in text drawing operations.

`pattern`
  [NOT YET IMPLEMENTED] Pattern to use in filling and stroking operations. If None, the foreground color is used as a solid fill. If a pixmap, it is replicated over the area to be painted. If the pixmap is 1 bit deep, it is colored using the foreground and background colors; otherwise the foreground and background colors are ignored. Implementations may impose a limit on the size of a pixmap that can be used as a pattern.

## Primitive methods

`newpath()`
  Clears the current path.
`moveto(`x`,` y`)`
  Moves the current point to (x, y). A subsequent call to `lineto` or `rlineto` will start a new segment of the current path.
`lineto(`x`,` y`)`
  Adds a straight line to the the current path from the current point to (x, y), and then makes (x, y) the current point.
`rmoveto(`dx`,` dy`)`
`rlineto(`dx`,` dy`)`
  Same as `moveto` and `lineto`, except that the coordinates are measured relative to the current point.
`closepath()`
  Closes the last segment of the current path by adding a straight line from its last point to its first point. A subsequent call to `lineto` or `rlineto` will start a new segment of the current path.

`stroke()`
  Draws a line along the current path using the current pen size and foreground color. The width of the line is distributed as evenly as possible either side of the path. The treatment of joins between lines is implementation-dependent.
`fill()`
  Fills the interior of the current path with the current foreground color. The interior of the path is determined using the even-odd winding number rule.

`erase()`
  [NOT YET IMPLEMENTED] Fills the interior of the current path with the current background color.

`show_text(`string`)`
  Draws the given text using the current font and foreground color. The baseline of the text starts at the current point. After drawing, the current point is advanced along the baseline by the width of the characters drawn.

`image(`pixmap, src_x, src_y, src_width, src_height, dst_x, dst_y`)`
  [NOT YET IMPLEMENTED] Copy specified region of pixmap onto the canvas. If the pixmap is 1 bit deep, it is colored using the current foreground and background colors.

`clip()`
  Replaces the current clipping region with the intersection of the current clipping region and the interior of the current path. The interior of the path is determined using the even-odd winding number rule.
`rectclip(`rect`)`
  Replaces the current clipping region with the intersection of the current clipping region and the given rectangle.
`initclip()`
  Sets the current clipping region to its initial value for this canvas. The initial clipping region depends on the type of canvas and the circumstances under which it was created. For a canvas passed to a view's `draw` method, it is the region of the view requiring drawing. For a canvas obtained by calling a view's `with_canvas` method, it is the viewed rectangle.

`gsave()`
  Pushes the current graphics state onto the graphics state stack.

`grestore()`
  Pops the most recently saved graphics state from the graphics state stack and makes it the current graphics state.
`initgraphics()`
  Sets all the elements of the current graphics state to default or initial values.

## Higher-level drawing methods

Note: The effect of these methods on the current path is undefined.

> `fill_rect(`rect`)`
>   Fills the specified rectangle with the current foreground color.
> `frame_rect(`rect`)`
>   Draws a line with the current pen size and foreground color just inside the specified rectangle. Note that this is not the same as stroking the path defined by the rectangle, but is equivalent to stroking a path which is smaller by half the pen size.
> `fill_oval(`rect)
>   Fills the ellipse that fits within the specified rectangle.
> `frame_oval(`rect`)`
>   Draws a line around the inside of the ellipse that fits within the specified rectangle.
> `fill_arc(`rect, start_angle, arc_angle`)`
>   Fills a pie-shaped wedge of the ellipse that fits within the specified rectangle. The angles are in degrees clockwise, and are scaled according to the aspect ratio of the rectangle, so that e.g. an angle of 45 degrees always passes through one corner of the rectangle. The start angle is measured from the 3 o'clock position, and the arc angle is measured relative to the start position.
> `frame_arc(`rect, start_angle, end_angle`)`
>   Draws an arc of the ellipse defined by the given rectangle and angles. See `fill_arc`.

> `fill_poly(`points`)`
>   Fills the polygon defined by the given sequence of points. Equivalent to constructing a closed path from the points and then filling it.

---