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