cs1lib User’s GuideThis page describes the functions in cs1lib.py that you can call. Here’s a link to the qt version of cs1lib, which requires that you have PySide installed. You can test cs1lib.py by running it; if you would like to test whether it draws images, download star.png and put it in the same directory as cs1lib.py.
This guide is organized according to what the functions do.
Here is a small editor where you can try out cs1lib functions using the browser version of the library. A few functions, including those that pertain to loading and drawing of images and setting fonts, are not included in the browser version.
start_graphics(draw_func, frames, data, framerate, title, width, height, mouse_press, mouse_release, mouse_move, key_press, key_release):
Call this function to create a graphics window. The only required
parameter is func, which is a Python function taking no
parameters. After start_graphics creates the graphics
window, it calls func, which should draw into the window.
title is a string giving the graphics window’s title,
defaulting to cs1 if omitted. width and
height give the graphics window’s width and height in
pixels, both defaulting to 400 if omitted.
is_key_pressed(key): returns True if
the key described by the string key is pressed. For
example, is_key_pressed("a").
mouse_x() and mouse_y(): return the
current x and y coordinates of the mouse.
is_mouse_pressed(): returns True if the
main mouse button is currently held down.
cs1_quit(): This parameterless function makes your
entire Python program terminate, closing the graphics window as
well.
clear(): This parameterless function clears the
entire graphics window. The cleared window will be filled with the
background color.
draw_point(x, y): This function draws a single pixel
at the coordinates given by x and y. The
stroke must be enabled (i.e., disable_stroke() must not
have been called more recently than enable_stroke()), and
the pixel is drawn in the current stroke color.
draw_line(x1, y1, x2, y2): This function draws a
line with endpoints (x1, y1) and
(x2, y2). The stroke must be enabled (i.e.,
disable_stroke() must not have been called more recently
than enable_stroke()), and the line is drawn in the current
stroke color.
draw_rectangle(x, y, w, h): This function draws a
rectangle whose upper left corner is at (x, y)
and whose width and height (in pixels) are w and
h, respectively. If filling is enabled (i.e.,
disable_fill() has not been called more recently than
enable_fill()), then the rectangle is filled with the
current fill color. If the stroke is enabled (i.e.,
disable_stroke() has not been called more recently than
enable_stroke()), then the outline is drawn in the current
stroke color.
draw_circle(x, y, r): This function draws a circle
whose center is at (x, y) and whose radius (in
pixels) is r. If filling is enabled (i.e.,
disable_fill() has not been called more recently than
enable_fill()), then the circle is filled with the current
fill color. If the stroke is enabled (i.e.,
disable_stroke() has not been called more recently than
enable_stroke()), then the outline is drawn in the current
stroke color.
draw_ellipse(x, y, rx, ry): This function draws an
ellipse whose center is at (x, y) and whose
horizontal and vertical radii (in pixels) are rx and
ry, respectively. If filling is enabled (i.e.,
disable_fill() has not been called more recently than
enable_fill()), then the ellipse is filled with the current
fill color. If the stroke is enabled (i.e.,
disable_stroke() has not been called more recently than
enable_stroke()), then the outline is drawn in the current
stroke color.
draw_triangle(x1, y1, x2, y2, x3, y3): This function
draws a triangle whose vertices (corners) are at the points
(x1, y1), (x2, y2),
and (x3, y3). If filling is enabled (i.e.,
disable_fill() has not been called more recently than
enable_fill()), then the triangle is filled with the
current fill color. If the stroke is enabled (i.e.,
disable_stroke() has not been called more recently than
enable_stroke()), then the outline is drawn in the current
stroke color.
draw_polygon(vertices): This function draws a
polygon whose vertices (corners) are given by the parameter
vertices. The parameter is a list of vertices, and each
vertex in the list is a list of exactly two numbers, giving the
x- and y-coordinates of the vertex. For example, to
draw a polygon with vertices (0, 0), (100, 100), and (50, 100), you
could call draw_polygon([[0, 0], [100, 100], [50, 100]]).
If filling is enabled (i.e., disable_fill() has not been
called more recently than enable_fill()), then the polygon
is filled with the current fill color. If the stroke is enabled (i.e.,
disable_stroke() has not been called more recently than
enable_stroke()), then the outline is drawn in the current
stroke color.
draw_text(string, x, y): This function draws text.
The text to draw is a string given by the parameter string.
The location of the text depends on the remaining parameters. The stroke
must be enabled (i.e., disable_stroke() must not have been
called more recently than enable_stroke()), and the text is
drawn in the current stroke color.
draw_image(image, x, y, cx, cy, theta): This
function draws an image that has been returned by a previous call to load_image. The parameter
image is required and specifies the image. The parameters
x, y, cx, and cy
specify where in the graphics window the image is placed. The parameters
x and y are required, and cx and
cy are optional. If cx and cy are
omitted, then x and y give the coordinates of
where the upper left corner of the image will appear. If cx
and cy are given, then they give a position in the image
(in pixels, from the upper left) that will map to coordinates
x and y in the graphics window. For example,
in the call draw_image(image, 100, 200, 25, 50), the pixel
that is 25 pixels into the image horizonatally and 50 pixels into the
image vertically will appear at coordinates (100, 200) in the graphics
window; in other words, the entire image will be shifted 25 pixels to
the left and 50 pixels up so that the upper left corner appears at
coordinates (75, 150) in the graphics window. The last parameter,
theta, is optional and specifies how many degrees to rotate
the image. The setting of the stroke and fill have no effect on drawing
images.
These functions, on their own, do not cause anything to change in the
graphics window. They affect how future calls of functions that draw
into the graphics window will behave. The most recent call of these
functions will be in effect whenever a drawing function is called. For
example, if disable_fill() was called more recently than
enable_fill() and
draw_rectangle(0, 0, 100, 200) is called, then the
rectangle will be drawn unfilled.
enable_fill(), disable_fill(): These
parameterless functions make it so that rectangles, circles, ellipses,
triangles, and polygons are drawn either filled or not filled. The
default is that filling is enabled, i.e., if you never call either of
these functions, then it’s the same as having called
enable_fill().
enable_stroke(), disable_stroke():
These parameterless functions make it so that rectangles, circles,
ellipses, triangles, and polygons are drawn either with or without an
outline. They also affect whether points, lines, and text are drawn at
all. The default is that the stroke is enabled, i.e., if you never call
either of these functions, then it’s the same as having called
enable_stroke().
set_fill_color(r, g, b, alpha): This function sets
the fill color for filled shapes. The parameters r,
g, and b are fractions in the range 0.0 to
1.0, inclusive, giving how much red, green, and blue to combine to make
the fill color. The parameter alpha is optional; it’s a
fraction in the range 0.0 to 1.0, inclusive, giving the opaqueness of
the color. The default is 1.0, meaning that the color is fully opaque; a
value of 0.0 would make the color completely transparent.
Some sample color combinations:
| Color | r | g | b |
|---|---|---|---|
| red | 1 | 0 | 0 |
| green | 0 | 1 | 0 |
| blue | 0 | 0 | 1 |
| white | 1 | 1 | 1 |
| black | 0 | 0 | 0 |
| gray | 0.5 | 0.5 | 0.5 |
| light gray | 0.75 | 0.75 | 0.75 |
| dark gray | 0.25 | 0.25 | 0.25 |
| orange | 1 | 0.5 | 0 |
| yellow | 1 | 1 | 0 |
| purple | 0.25 | 0 | 0.5 |
| magenta | 1 | 0 | 1 |
| cyan | 0 | 1 | 1 |
| brown | 0.5 | 0.4 | 0.2 |
set_stroke_color(r, g, b, alpha): Like
set_fill_color, but sets the color for the stroke (points,
lines, outlines of shapes, and text).
set_clear_color(r, g, b, alpha): Like
set_fill_color, but sets the color for the graphics
window’s background, which will be displayed upon the next call to
clear().
set_stroke_width(width): This function sets the
width of the stroke, in pixels, for points, lines, and outlines of
shapes. This function has no effect on how text appears.
set_font(font_name): This function sets the font
used in subsequent calls to draw_text. The parameter
font_name is a string containing the name of the font. You
may use any font installed on your system, so that valid parameters
would include "Helvetica", "Times", or
"Palatino“, among others.
set_font_size(font_size): This function sets the
size of the font used, in points, in subsequent calls to
draw_text. The font size is given by the parameter
font_size.
set_font_bold(): This parameterless function makes
it so that subsequent calls to draw_text render the current
font in boldface.
set_font_italic(): This parameterless function makes
it so that subsequent calls to draw_text render the current
font in italics.
set_font_normal(): This parameterless function makes
it so that subsequent calls to draw_text render the current
font normally, i.e., not bold or italic.
load_image(filename): This
function takes an image from a file whose name is given by
filename and returns an object representing that image.
This returned object may be given in a subsequent call to
draw_image to render the image in the graphics
window.
get_text_width(string): This function returns the
width, in pixels, of the string passed as the parameter
string.
get_text_height(): This function returns the height,
in pixels, of any string. (No parameter is needed.)
