CSC111 Necaise's Graphics Library
--D. Thiebaut (talk) 21:20, 6 April 2014 (EDT)
This is a modified (fixed some bugs) version of Horstmann's graphics library available here.
# graphics.py
# (c) 2013 by Rance Necaise
# http://graphics.necaiseweb.org
#
# Permission is hereby granted, free of charge, to any person obtaining a copy of
# this software and associated documentation files (the "Software"), to deal in
# the Software without restriction, including without limitation the rights to
# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
# the Software, and to permit persons to whom the Software is furnished to do so,
# subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
## graphics.py
# version 1.0
# This module is part of the PyWare open source project that provides modules and
# and tools for use in the classroom. This module provides classes for creating
# top-level GUI windows that can be used for creating and displaying simple
# geometric shapes and color digital images. Complete documentation of the module
# is available at http://graphics.necaseweb.org.
## Version 1.1
# modified by D. Thiebaut to allow better use of drawPoly()
#
import tkinter as tk
## This class defines a basic top level window that can be opened on the
# desktop and used to produce simple graphical drawings. It contains a
# canvas on which geometric shapes can be drawn and manipulated.
#
class GraphicsWindow :
## Creates a new graphics window with an empty canvas.
# @param width The horizontal size of the canvas in pixels.
# @param height The vertical size of the canvas in pixels.
#
def __init__(self, width = 400, height = 400) :
global TheMainWindow
# Is the window open or closed. It must be open to use most operations.
self._isClosed = False
# If this is the first toplevel window, remember it as the main window. The
# event loop is only terminated when the main window is closed.
if TheMainWindow is None :
TheMainWindow = self
# Create a top-level window for the graphics window.
self._tkwin = tk.Toplevel(rootWin, padx=0, pady=0, bd=0)
self._tkwin.protocol("WM_DELETE_WINDOW", self.close)
self._tkwin.title("")
# Create a canvas inside the top-level window which is used for
# drawing the graphical objects and text.
self._canvas = GraphicsCanvas( self, width, height )
# Bring the window to the front of all other windows and force an update.
self._tkwin.lift()
self._tkwin.resizable(0, 0)
self._tkwin.update_idletasks()
## Closes and destroys the window. A closed window can not be used.
#
def close(self) :
# Set the closed flag to true so no other ops can be performed on
# the window object.
if self._isClosed : return
self._isClosed = True
# Destroy the window and force an update so it will close when
# used in IDLE or Wing IDE.
self._tkwin.destroy()
self._tkwin.update_idletasks()
# If the main window is being closed, then the mainloop has to be terminated.
if self is TheMainWindow :
self._tkwin.quit()
## Starts the event loop which handles various window events. This causes
# the sequential execution of the program to stop and wait for the user
# to click the close button on the main window or to call the quit method
# on any window. This method should only be called on the main window.
#
def wait(self) :
if not self._isClosed :
self._tkwin.mainloop()
## Returns a reference to the canvas contained within the window.
# The canvas can be used to draw and manipulate geometric shapes and text.
# @return A reference to the GraphicsCanvas contained in the window.
#
def canvas(self) :
if self._isClosed : raise GraphicsWinError()
return self._canvas
## Sets the title of the window. By default, the window has no title.
# @param title A text string to which the title of the window is set. To
# remove the title, use pass an empty string to the method.
#
def setTitle(self, title) :
self._tkwin.title( title )
## Returns a Boolean indicating whether the window exists or was previously closed.
# Window operations can not be performed on a closed window.
# @return @c True if the window is closed and @c False otherwise.
#
def isClosed(self) :
return self._isClosed
## Hides or iconifies the top level window.
# The window still exists and can be displayed again using the show method.
#
def hide(self) :
if self._isClosed : raise GraphicsWinError()
self._tkwin.withdraw()
self._tkwin.update_idletasks()
## Shows or deiconifies a previously hidden top level window.
#
def show(self) :
if self._isClosed : raise GraphicsWinError()
self._tkwin.deiconify()
self._tkwin.update_idletasks()
#--- The graphics canvas.
## This class defines a canvas on which geometric shapes and text can be
# drawn. The canvas uses discrete Cartesian coordinates >= 0 with (0,0)
# being in the upper-left corner of the window. Unlike a canvas that a
# painter might use, shapes drawn on a graphics canvas are stored as
# objects that can later be reconfigured without having to redraw them.
# A collection of shape properties are also maintained as part of the
# canvas. These properties, which can be changed by calling specific
# methods, are used in drawing the various shapes and text. All shapes
# and text are drawn using the current context or the property settings
# at the time the shape is first drawn.
#
class GraphicsCanvas :
## Creates a new empty graphics canvas. A graphics canvas is
# automatically created as part of a GraphicsWindow. Thus, there should
# be no need for the user of this module to explicitly create one.
# @param win, A reference to the GraphicsWindow in which the canvas is used.
# @param width, (int) The width of the canvas in pixels.
# @param height, (int) The height of the canvas in pixels.
#
def __init__(self, win, width, height) :
# The GraphicsWindow that contains the canvas.
self._win = win
# Keep track of the size of the canvas.
self._width = width
self._height = height
# Maintain the options used for drawing objects and text.
self._polyOpts = {"outline" : "black", "width" : 1, "dash" : None, "fill" : ""}
self._textOpts = {"text" : "", "justify" : tk.LEFT, "anchor" : tk.NW,
"fill" : "black",
"font" : ("helvetica", 10, "normal") }
# Create the tk canvas inside the given window.
self._tkcanvas = tk.Canvas(self._win._tkwin, highlightthickness = 0,
width = width, height = height, bg = "white" )
self._tkcanvas.pack()
## Changes the height of the canvas.
# The window is resized to fit the size of the canvas.
# @param size (int) The new height of the canvas in number of pixels.
#
def setHeight(self, size) :
self._checkValid()
if type(size) != int or size <= 0 :
raise GraphicsParamError( "The window height must be >= 1." )
self._tkcanvas.config(height=size)
self._height = size
self._tkcanvas.update_idletasks()
## Changes the width of the canvas.
# The window is resized to fit the size of the canvas.
# @param size (int) The new width of the canvas in number of pixels.
#
def setWidth(self, size) :
self._checkValid()
if type(size) != int or size <= 0 :
raise GraphicsParamError( "The window width must be >= 1." )
self._tkcanvas.config(width=size)
self._width = size
self._tkcanvas.update_idletasks()
## Returns the height of the canvas.
# @return The canvas height in number of pixels.
#
def height( self ):
return self._height
## Returns the width of the canvas.
# @return The canva width in number of pixels.
#
def width( self ):
return self._width
## Clears the canvas by removing all items previously drawn on it. The canvas
# acts as a container of shapes and text. Thus, when a geometric shape or
# text is drawn on the canvas, it is maintained internally as an object
# until cleared.
#
def clear(self):
self._checkValid()
self._tkcanvas.delete(tk.ALL)
self._tkcanvas.update_idletasks()
## Sets the current background color of the canvas. The color can either
# be specified as a string that names a color or as three integer values
# in the range [0..255].
#
# c.setBackground(colorname)
# c.setBackground(red, green, blue)
#
def setBackground(self, red, green = None, blue = None) :
if type(red) == int :
color = "#%02X%02X%02X" % (red, green, blue)
elif type(red) != str :
raise GraphicsParamError( "Invalid color." )
else :
color = red
self._checkValid()
self._tkcanvas.config(bg = color)
self._tkcanvas.update_idletasks()
## Sets the fill color used when drawing new polygon shapes. The color
# can be specified either as a string that names the color or as three
# integer values in the range [0..255]. If no argument is provided, it
# clears the fill color and the shapes will be drawn in outline form only.
#
# c.setFill()
# c.setFill(colorname)
# c.setFill(red, green, blue)
#
def setFill( self, red = None, green = None, blue = None) :
if red is None :
color = ""
elif type(red) == int :
color = "#%02X%02X%02X" % (red, green, blue)
elif type(red) != str :
raise GraphicsParamError( "Invalid color." )
else :
color = red
self._polyOpts["fill"] = color
## Sets the outline color used when drawing new polygon shapes and the
# color used to draw lines, pixels, and text. The color can be specified
# either as a string that names the color or as three integer values in
# the range [0..255]. If no argument is provided, it clears the outline
# color. A cleared outline color is only meant for drawing polygon type
# shapes that are only filled, without an outline.
#
# c.setOutline()
# c.setOutline(colorname)
# c.setOutline(red, green, blue)
#
def setOutline( self, red = None, green = None, blue = None) :
if red is None :
color = ""
elif type(red) == int :
color = "#%02X%02X%02X" % (red, green, blue)
elif type(red) != str :
raise GraphicsParamError( "Invalid color." )
else :
color = red
self._polyOpts["outline"] = color
self._textOpts["fill"] = color
## Sets both the fill and outline colors used when drawing shapes and text
# on the canvas. The color can be specified either as a string that names
# the color or as three integer values in the range [0..255].
#
# c.setFill(colorname)
# c.setFill(red, green, blue)
#
def setColor( self, red, green = None, blue = None ) :
if type(red) == int :
color = "#%02X%02X%02X" % (red, green, blue)
elif type(red) != str :
raise GraphicsParamError( "Invalid color." )
else :
color = red
self._polyOpts["outline"] = color
self._polyOpts["fill"] = color
self._textOpts["fill"] = color
## Sets the width of lines drawn on the canvas. This includes the line and
# vector shapes and the outlines of polygons.
# @param size (int) The new line width in number of pixels.
#
def setLineWidth(self, size) :
if type(size) != int or size <= 0 :
raise GraphicsParamError( "Invalid line width." )
self._polyOpts["width"] = size
## Sets the style used to drawn lines on the canvas. This includes the line
# and vector shapes and the outlines of polygons.
# @param style (str) The style to use for new lines. It can be either
# "solid" or "dashed".
#
def setLineStyle(self, style) :
if style == "solid" :
self._polyOpts["dash"] = None
elif style == "dashed" :
self._polyOpts["dash"] = (4,)
else :
raise GraphicsParamError("Invalid line style.")
## Sets the font used to draw text on the canvas.
# @param family (str) The font family. It can be one of:
# "arial", "courier", "times", "helvetica".
# @param size (int) The point size of the font.
# @param style (string) The font style. It can be one of:
# "normal", "bold", "italic", or "bold italic".
#
def setTextFont(self, family = None, size = None, style = None) :
origFamily, origSize, origStyle = self._fontOpts["font"]
if (family is not None and
family not in ('helvetica', 'arial', 'courier', 'times', 'times roman')) :
raise GraphicsParamError( "Invalid font family." )
else :
family = origFamily
if (style is not None and
style not in ('bold', 'normal', 'italic', 'bold italic')) :
raise GraphicsParamError( "Invalid font style." )
else :
style = origStyle
if size is not None and (type(size) != int or size <= 0) :
raise GraphicsParamError( "Invalid font size." )
else :
size = origSize
self._textOpts["font"] = (family, size, style)
## Sets the position that text is drawn in relation to a bounding box.
# The (x, y) coordinate provided with drawText() is anchored to a spot on
# the bounding box that surrounds the text and the text is positioned
# relative to the anchor.
# @param position A string indicating the anchor position on the
# bounding box. It can be one of:
# "n", "s", "e", "w", "center", "nw", "ne", "sw", "se".
#
def setTextAnchor(self, position) :
if position not in ('n', 's', 'e', 'w', 'nw', 'ne', 'sw', 'se', 'center') :
raise GraphicsParamError( "Invalid anchor position." )
self._textOpts["anchor"] = position
## Sets the justification used to draw new multiline text on the canvas..
# @param style A string specifying the justification. It can be one of:
# "left", "center", or "right".
#
def setTextJustify(self, style) :
if style == "left" :
self._fontOpts["justify"] = tk.LEFT
elif style == "center" :
self._fontOpts["justify"] = tk.CENTER
elif style == "right" :
self._fontOpts["justify"] = tk.RIGHT
else :
raise GraphicsParamError( "Invalid justification value." )
#--- The shape drawing methods.
## Draws or plots a single point (pixel) on the canvas.
# @param x, y Integers indicating the (x, y) pixel coordinates at which
# the point is drawn.
# @return An integer that uniquely identifies the new canvas item.
#
def drawPoint( self, x, y ):
self._checkValid()
obj = self._tkcanvas.create_line( x, y, x+1, y,
fill=self._polyOpts["outline"],
width=self._polyOpts["width"] )
self._tkcanvas.update_idletasks()
return obj
## Draws a line segment on the canvas. The line is drawn between two
# discrete end points.
# @param x1, y1 The coordinates of the starting point.
# @param x2, y2 The coordinates of the ending point.
# @return An integer that uniquely identifies the new canvas item.
#
def drawLine(self, x1, y1, x2, y2) :
self._checkValid()
obj = self._tkcanvas.create_line( x1, y1,
x2, y2,
fill=self._polyOpts["outline"],
width=self._polyOpts["width"],
dash=self._polyOpts["dash"] )
self._tkcanvas.update_idletasks()
return obj
## Draws an arrow or vector on the canvas. The same as a line segment,
# except an arrow head is drawn at the end of the segment.
# @returns An integer that uniquely identifies the new canvas item.
#
def drawArrow(self, x1, y1, x2, y2) :
self._checkValid()
obj = self._tkcanvas.create_line( x1, y1, x2, y2,
fill=self._polyOpts["outline"],
width=self._polyOpts["width"],
dash=self._polyOpts["dash"],
arrow=tk.LAST )
self._tkcanvas.update_idletasks()
return obj
## Draws a rectangle on the canvas. The rectangle is defined by the coordinates
# of the upper left corner of the rectangle and its width and height.
# @param x, y The coordinates of the upper-left corner of the rectangle.
# @param width, height The dimensions of the rectangle.
# @returns An integer that uniquely identifies the new canvas item.
#
def drawRectangle(self, x, y, width, height) :
self._checkValid()
obj = self._tkcanvas.create_rectangle(x, y, x + width, y + height, self._polyOpts )
self._tkcanvas.update_idletasks()
return obj
## The same as drawRectangle().
#
def drawRect(self, x, y, width, height) :
return self.drawRectangle(x, y, width, height)
## Draws a polygon on the canvas. The polygon is defined by three or more vertices
# specified in counter-clockwise order. There are two forms of the method:
#
# c.drawPolygon(x1, y1, x2, y2, ..., xN, yN)
# c.drawPolygon(sequence)
#
# @returns An integer that uniquely identifies the new canvas item.
#
def drawPolygon( self, *coords ):
# Unwrap the cooridinates which allows the method to accept individual vertices
# or a list of vertices.
print( "drawPolygon: coords = ", coords )
if len(coords) == 1 and (type(coords[0]) == list or type(coords[0] == tuple)) :
expCoords = tuple(*coords)
else :
expCoords = coords
#print( "expCoords = ", expCoords )
self._checkValid()
if len(expCoords) < 6 :
raise GraphicsParamError( "At least 3 vertices must be provided." )
obj = self._tkcanvas.create_polygon( expCoords, self._polyOpts )
self._tkcanvas.update_idletasks()
return obj
## The same as drawPolygon().
#
def drawPoly(self, *coords) :
# code added by DFT, April 2014
if len(coords) == 1 and (type(coords[0]) == list or type(coords[0] == tuple)) :
expCoords = tuple(*coords)
else :
expCoords = coords
#print( "drawPoly: coords = ", coords )
return self.drawPolygon(coords)
## Draws an oval on the canvas. The oval is defined by a bounding rectangle
# that is specified by the coordinates of its upper-left corner and its
# dimensions.
# @param x, y The upper-left coordinates of the bounding rectangle.
# @param width, height The dimensions of the bounding rectangle.
# @returns An integer that uniquely identifies the new canvas item.
#
def drawOval( self, x, y, width, height ):
self._checkValid()
obj = self._tkcanvas.create_oval( x, y, x + width, y + height, self._polyOpts )
self._tkcanvas.update_idletasks()
return obj
## Draws an arc or part of a circle on the canvas. The arc is defined by a
# bounding square and two angles. The angles are specified in degrees with
# zero degrees corresponding to the x-axis.
# @param x, y The upper-left coordinates of the bounding square.
# @param diameter The dimensions of the bounding rectangle.
# @param startAngle The angle in degrees at which the arc begins.
# @param extent The extent of the arc given as an angle in degrees.
# @returns An integer that uniquely identifies the new canvas item.
#
def drawArc( self, x, y, diameter, startAngle, extent ):
self._checkValid()
obj = self._tkcanvas.create_arc( x, y, x + diameter, y + diameter, self._polyOpts,
start=startAngle, extent=extent )
self._tkcanvas.update_idletasks()
return obj
## Draws text on the canvas. The text is drawn such that an anchor point on a
# bounding box is positioned at a given point on the canvas. The default
# position of the anchor is in the upper-left (northwest) corner of the
# bounding box. The anchor position can be changed using the setTextAnchor()
# method. The text is drawn using the default font family, size, and style.
# The setTextFont() method can be used to change those characteristics. The
# text to be drawn can consists of multiple lines, each separated by a
# newline character. The justification of the text can be set when drawing
# multiple lines of text.
# @param x, y The position on the canvas at which the anchor point of the
# bounding box is positioned.
# @param text A string containing the text to be drawn on the canvas.
#
def drawText(self, x, y, text) :
self._checkValid()
self._textOpts["text"] = text
obj = self._tkcanvas.create_text( x, y, self._textOpts )
self._tkcanvas.update_idletasks()
return obj
#--- Methods that can be used to manipulate the item previously drawn on the
#--- canvas. Each drawing method returns a unique id number used to identify
#--- the resulting shape. See the online documentation for more information.
def shiftItem(self, itemId, dx, dy) :
self._checkContains(itemId)
self._tkcanvas.move(itemId, dx, dy)
self._tkcanvas.update_idletasks()
def removeItem(self, itemId) :
self._checkContains(itemId)
self._tkcanvas.delete(itemId)
self._tkcanvas.update_idletasks()
def showItem(self, itemId) :
self._checkContains(itemId)
self._tkcanvas.itemconfig(itemId, state = "normal")
self._tkcanvas.update_idletasks()
def hideItem(self, itemId) :
self._checkContains(itemId)
self._tkcanvas.itemconfig(itemId, state = "hidden")
self._tkcanvas.update_idletasks()
def raiseItem(self, itemId, above = None) :
self._checkContains(itemId)
self._tkcanvas.tag_raise(itemId)
self._tkcanvas.update_idletasks()
def lowerItem(self, itemId, below = None) :
self._checkContains(itemId)
self._tkcanvas.tag_lower(itemId)
self._tkcanvas.update_idletasks()
def __contains__(self, itemId):
if self._tkcanvas.winfo_ismapped() :
return len(self._tkcanvas.find_withtag(itemId)) > 0
else :
return False
def itemType(self, itemId) :
self._checkContains(itemId)
return self._canvas.type(itemId)
def items( self ):
self._checkValid()
return self.find_all()
#--- Helper methods.
def _checkValid( self ):
if self._win.isClosed() :
raise GraphicsWinError()
def _checkContains(self, itemId) :
if self._win.isClosed() : raise GraphicsWinError()
if itemId in self : raise GraphicsObjError()
## This class defines a basic top level window that can contains a digital
# image, the pixels of which can be accessed or set.
#
class ImageWindow :
## Creates a new image window with an empty image.
# @param width The horizontal size of the image in pixels.
# @param height The vertical size of the image in pixels.
#
def __init__(self, width = 400, height = 400):
global TheMainWindow
# Is the window open or closed. It must be open to use most operations.
self._isClosed = False
# If this is the first toplevel window, remember it as the main window. The
# event loop is only terminated when the main window is closed.
if TheMainWindow is None :
TheMainWindow = self
# Create a top-level window for the graphics window.
self._tkwin = tk.Toplevel(rootWin, width=width, height=height,
borderwidth=0, padx=0, pady=0, bd=0)
self._tkwin.protocol("WM_DELETE_WINDOW", self.close)
self._tkwin.title("")
# Create the photo image and tk canvas inside the window.
self._tkimage = tk.PhotoImage(width=width, height=height)
self._tkcanvas = tk.Canvas(self._tkwin, width=width, height=height,
bg = "white", bd = 0)
# Add the photo image object to the canvas.
self._tkcanvas.create_image(0, 0, anchor="nw", image=self._tkimage)
self._tkcanvas.pack()
# Bring the window to the front of all other windows and force an update.
self._tkwin.lift()
self._tkwin.resizable(0, 0)
self._tkwin.update_idletasks()
## Sets the title of the window. By default, the window has no title.
# @param title A text string to which the title of the window is set. To
# remove the title, use pass an empty string to the method.
#
def setTitle(self, title) :
self._tkwin.title( title )
## Returns a Boolean indicating whether the window exists or was previously closed.
# Window operations can not be performed on a closed window.
# @return @c True if the window is closed and @c False otherwise.
#
def isClosed(self) :
return self._isClosed
## Hides or iconifies the top level window.
# The window still exists and can be displayed again using the show method.
#
def hide(self) :
if self._isClosed : raise GraphicsWinError()
self._tkwin.withdraw()
self._tkwin.update_idletasks()
## Shows or deiconifies a previously hidden top level window.
#
def show(self) :
if self._isClosed : raise GraphicsWinError()
self._tkwin.deiconify()
self._tkwin.update_idletasks()
## Closes and destroys the window. A closed window can not be used.
#
def close( self ):
# Set the closed flag to true so no other ops can be performed on
# the window object.
if self._isClosed : return
self._isClosed = True
# Destroy the window and force an update so it will close when
# used in IDLE or Wing IDE.
self._tkwin.destroy()
self._tkwin.update_idletasks()
# Terminate the mainloop so the program will exit.
self._tkwin.quit()
## Starts the event loop which handles various window events. This causes
# the sequential execution of the program to stop and wait for the user
# to click the close button on the main window or to call the quit method
# on any window. This method should only be called on the main window.
#
def wait( self ):
if self._isClosed : raise GraphicsWinError()
self._tkwin.mainloop()
## Sets a pixel to a given RGB color.
# @param row, col The pixel coordinates.
# @param red, green, blue The discrete RGB color components in the range [0..255].
#
def setPixel(self, row, col, red, green, blue) :
self._tkimage.put("#%02x%02x%02x" % (red, green, blue), (col, row))
## Returns a 3-tuple containing the RGB color of a given pixel.
# @param row, col The pixel coordinates.
# @returns An RGB color as a 3-tuple.
#
def getPixel(self, row, col) :
string = self._tkimage.get(col, row)
parts = string.split()
return (int(parts[0]), int(parts[1]), int(parts[2]))
# --- Defines special graphics exceptions that are raised when an error
# --- occurs in a GraphicsWindow method.
class GraphicsError( Exception ) :
def __init__( self, message ):
super(GraphicsError, self).__init__( message )
class GraphicsObjError( GraphicsError ) :
def __init__( self ):
super(GraphicsObjectError, self).__init__( "Invalid object id." )
class GraphicsWinError( GraphicsError ) :
def __init__( self ):
super(GraphicsWinError, self).__init__(
"Operation can not be performed on a closed window." )
class GraphicsParamError( GraphicsError ) :
def __init__( self, message ):
super(GraphicsParamError, self).__init__( message )
# --- Create an invisible root window and initialize the Tk system.
rootWin = tk.Tk()
rootWin.withdraw()
# --- Remember the first toplevel window created which serves as the main window.
TheMainWindow = None
