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.
---