Module src.graphics

Classes

class Canvas (width=754, height=492)

Canvas is a simplified interface on top of the tkinter Canvas to allow for easier manipulation of graphical objects. Canvas has a variety of functionality to create, modify and delete graphical objects, and also get information about the canvas contents. Canvas is a subclass of tkinter.Canvas, so all tkinter functionality is also available if needed.

When creating a canvas, you can optionally specify a width and height. If no width and height are specified, the canvas is initialized with its default size.

Args

width
the width of the Canvas to create (or if not specified, uses Canvas.DEFAULT_WIDTH)
height
the height of the Canvas to create (or if not specified, uses Canvas.DEFAULT_HEIGHT)

Ancestors

  • tkinter.Canvas
  • tkinter.Widget
  • tkinter.BaseWidget
  • tkinter.Misc
  • tkinter.Pack
  • tkinter.Place
  • tkinter.Grid
  • tkinter.XView
  • tkinter.YView

Class variables

var BOTTOM

Directions to use for adding interactors to different sides of the canvas.
BOTTOM refers to the bottom of the window.

var COLORS

This is a list of names of all colors available to use for graphics on the Canvas. This list of Tkinter colors was taken from https://stackoverflow.com/questions/4969543/colour-chart-for-tkinter-and-tix.

var DEFAULT_HEIGHT

The default height of the canvas is 492.

var DEFAULT_TITLE

The default text shown in the canvas window titlebar is 'Canvas'.

var DEFAULT_WIDTH

The default width of the canvas is 754.

var LEFT

Directions to use for adding interactors to different sides of the canvas.
LEFT refers to the left side of the window.

var RIGHT

Directions to use for adding interactors to different sides of the canvas.
RIGHT refers to the right side of the window.

var TOP

Directions to use for adding interactors to different sides of the canvas.
TOP refers to the top side of the window.

Methods

def create_button(self, title, location, **kwargs)

Adds a button to the canvas with the specified title at the specified location. Buttons are added from left to right at the top and bottom of the window and top to bottom on the sides of the window.

Args

title
the title to display on the button. Must be unique among button names.
location
the region (Canvas.TOP/LEFT/BOTTOM/RIGHT) where the button should be added around the canvas.
kwargs
other tkinter keyword args

Returns

a reference to the button added to the window at the specified location. Use this with the .destroy() function to delete the button later if needed. E.g. button = create_button(…); button.destroy();

def create_image(self, x, y, file_path, **kwargs)

Creates an image with the specified filename at the specified position on the canvas. The image will be the same size as the image file loaded in.

Args

x
the x coordinate of the top-left corner of the image on the canvas
y
the y coordinate of the top-left corner of the image on the canvas
file_path
the path to the image file to load and display on the canvas
kwargs
other tkinter keyword args

Returns

the graphical image object that is displaying the specified image at the specified location.

def create_image_with_size(self, x, y, width, height, file_path, **kwargs)

Creates an image with the specified filename at the specified position on the canvas, and resized to the specified width and height.

Args

x
the x coordinate of the top-left corner of the image on the canvas
y
the y coordinate of the top-left corner of the image on the canvas
width
the width to set for the image
height
the height to set for the image
file_path
the path to the image file to load and display on the canvas
kwargs
other tkinter keyword args

Returns

the graphical image object that is displaying the specified image at the specified location with the specified size.

def create_line(self, x1, y1, x2, y2, *args, **kwargs)

Creates and returns a line graphical object on the screen from the specified point to the specified point. The line is drawn black.

Args

x1
the starting x location of the line
y1
the starting y location of the line
x2
the ending x location of the line
y2
the ending y location of the line
args
you can optionally specify additional points on the line or shape
kwargs
other tkinter keyword args

Returns

the graphical line object between the two specified points.

def create_oval(self, x1, y1, x2, y2, **kwargs)

Creates and returns an oval graphical object on the screen contained within the bounding box whose top left corner is the first coordinate, and whose bottom right corner is the second coordinate. The oval is drawn unfilled with a black outline.

Args

x1
the top-left x location of the bounding box
y1
the top-left y location of the bounding box
x2
the bottom-right x location of the bounding box
y2
the bottom-right y location of the bounding box
kwargs
other tkinter keyword args

Returns

the graphical oval object at the specified location.

def create_rectangle(self, x1, y1, x2, y2, *args, **kwargs)

Creates and returns a rectangle graphical object on the screen with its top-left corner at the first coordinate and its bottom-right corner at the second coordinate. The rect is drawn unfilled with a black outline.

Args

x1
the top-left x location of the rect
y1
the top-left y location of the rect
x2
the bottom-right x location of the rect
y2
the bottom-right y location of the rect
kwargs
other tkinter keyword args

Returns

the graphical rectangle object at the specified location.

def create_text(self, x, y, text, **kwargs)

Creates and returns a text graphical object on the screen at the specified location with the specified text. The specified x and y location is for the center of the text. The text will be in size 13 font.

Args

x
the x location of the center of the text
y
the y location of the center of the text
text
the text that should be displayed on the canvas at the given position
kwargs
other tkinter keyword args

Returns

the graphical text object that is displaying the specified text at the specified location.

def create_text_field(self, label, location, **kwargs)

Adds a label and text field pair to the canvas with the specified label text at the specified location. Interactors are added from left to right at the top and bottom of the window and top to bottom on the sides of the window. Stores a reference to this text field in the Canvas map of text fields.

Args

label
the label text to display next to the text field, and the name of the text field. Must be unique among text field names.
location
the region (Canvas.TOP/LEFT/BOTTOM/RIGHT) where the label/text field should be added around the canvas.
kwargs
other tkinter keyword args for the text field

Returns

a reference to the text field and the label (in that order) added to the window at the specified location.

def delete(self, obj)

Remove the specified graphical object from the canvas.

Args

obj
the graphical object to remove from the canvas
def delete_all(self)

Remove all graphical objects from the canvas.

def delete_text_field(self, text_field_name)

Removes the text field and corresponding label from both the canvas and the internal data structures tracking text fields.

Args

text_field_name
the name given when the text field was created.
def find_all(self)

Get a list of all graphical objects on the canvas.

Returns

a list of all graphical objects on the canvas.

def find_element_at(self, x, y)

Finds the topmost element overlapping this location.

Args

x
the x coordinate of the location
y
the y coordinate of the location

Returns

the top-most graphical object on the canvas at this location (None otherwise)

def find_overlapping(self, x1, y1, x2, y2)

Get a list of graphical objects on the canvas that overlap with the specified bounding box.

Args

x1
the x coordinate of the upper-left corner of the bounding box
y1
the y coordinate of the upper-left corner of the bounding box
x2
the x coordinate of the lower-right corner of the bounding box
y2
the y coordinate of the lower-right corner of the bounding box

Returns

a list of graphical objects on the canvas that overlap with this bounding box.

def get_canvas_background_color(self)

Gets the name of the background color of the canvas.

Returns

the color of the canvas background, as a string.

def get_canvas_height(self)

Get the height of the canvas.

Returns

the current height of the canvas.

def get_canvas_width(self)

Get the width of the canvas.

Returns

the current width of the canvas.

def get_fill_color(self, obj)

Gets the fill color of the specified graphical object. Cannot be used to get the fill color of non-fillable objects such as images - throws a tkinter.TclError.

Args

obj
the object for which to set the fill color

Returns

The current fill color of the object, as a string. If this is the empty string, the object is not filled.

def get_height(self, obj)

Returns the height of the specified graphical object.

Args

obj
the object for which to calculate the height

Returns

the height of the specified graphical object.

def get_left_x(self, obj)

Returns the leftmost x coordinate of the specified graphical object.

Args

obj
the object for which to calculate the leftmost x coordinate

Returns

the leftmost x coordinate of the specified graphical object.

def get_mouse_x(self)

Returns the mouse's current X location on the canvas.

Returns

the mouses's current X location on the canvas.

def get_mouse_y(self)

Returns the mouse's current Y location on the canvas.

Returns

the mouse's current Y location on the canvas.

def get_new_button_clicks(self)

Returns a list of all button clicks that have occurred since the last call to this function or any registered button handler.

Returns

a list of all button clicks that have occurred since the last call to this function or any registered button handler. Each button click is the name of the button clicked, e.g. clicks = canvas.get_new_button_clicked(); print(clicks[0]).

def get_new_key_presses(self)

Returns a list of all key presses that have occurred since the last call to this function or any registered key handler.

Returns

a list of all key presses that have occurred since the last call to this function or any registered key handler. Each key press contains a keysym property for the key pressed, e.g. presses = canvas.get_new_key_presses(); print(presses[0].keysym).

def get_new_mouse_clicks(self)

Returns a list of all mouse clicks that have occurred since the last call to this function or any registered mouse handler.

Returns

a list of all mouse clicks that have occurred since the last call to this function or any registered mouse handler. Each mouse click contains x and y properties for the click location, e.g. clicks = canvas.get_new_mouse_clicks(); print(clicks[0].x).

def get_outline_color(self, obj)

Gets the outline color of the specified graphical object. Cannot be used to get the outline color of non-outlined objects such as images or text - throws a tkinter.TclError.

Args

obj
the object for which to get the outline color

Returns

the outline color of the given object, as a string. If this is the empty string, the object does not have an outline.

def get_random_color(self)

Returns a randomly-selected color.

Returns

A randomly-selected color, as a string.

def get_text(self, obj)

Returns the text displayed by the given text object. Cannot be used on any non-text graphical object.

Args

obj
the text object for which to get the displayed text

Returns

the text currently displayed by this graphical object.

def get_text_field_text(self, text_field_name)

Returns the current contents of the text field with the specified name.

Args

text_field_name
the name given when the text field was created.

Returns

the current contents of the given text field, or None if there is no text field with the given name.

def get_top_y(self, obj)

Returns the topmost y coordinate of the specified graphical object.

Args

obj
the object for which to calculate the topmost y coordinate

Returns

the topmost y coordinate of the specified graphical object.

def get_width(self, obj)

Returns the width of the specified graphical object.

Args

obj
the object for which to calculate the width

Returns

the width of the specified graphical object.

def is_hidden(self, obj)

Gets whether or not the given graphical object is hidden or visible on the canvas.

Args

obj
the graphical object to get the state of

Returns

True if the given graphical object is hidden, or False otherwise.

def lower_behind(self, obj, behind)

Sets the first object to be directly behind the second object in Z-ordering on the canvas. In other words, the first object will now appear directly behind the second object and all objects in front of the second object, but in front of all objects that the second object is also in front of.

Args

obj
the object to put in front of the second object
behind
the object to put the first object directly behind
def lower_to_back(self, obj)

Sends the given object to be behind all the other objects on the canvas

Args

obj
the object to put behind all other objects on the canvas
def mouse_is_on_canvas(self)

Returns whether or not the mouse is currently on the canvas.

Returns

True if the mouse is currently on the canvas, or False otherwise.

def move(self, obj, dx, dy)

Moves the specified graphical object by the specified amounts in the x and y directions.

Args

obj
the object to move
dx
the amount by which to change the object's x position
dy
the amount by which to change the object's y position
def move_to(self, obj, new_x, new_y)
def moveto(self, obj, x='', y='')

Moves the specified graphical object to the specified location, which is its bounding box's new upper-left corner.

Args

obj
the object to move
x
the new x coordinate of the upper-left corner for the object
y
the new y coordinate of the upper-left corner for the object
def raise_in_front_of(self, obj, above)

Sets the first object to be directly in front of the second object in Z-ordering on the canvas. In other words, the first object will now appear in front of the second object and all objects behind the second object, but behind all objects that the second object is also behind.

Args

obj
the object to put in front of the second object
above
the object to put the first object directly in front of
def raise_to_front(self, obj)

Sends the given object to the very front of all the other objects on the canvas.

Args

obj
the object to bring to the front of the objects on the canvas
def set_canvas_background_color(self, color)

Sets the background color of the canvas to the specified color string.

Args

color
the color (string) to make the background of the canvas.
def set_canvas_size(self, width, height)

Sets the size of the canvas and its containing window to the specified width and height.

Args

width
the width to set for the canvas and containing window
height
the height to set for the canvas and containing window
def set_canvas_title(self, title)

Sets the title text displayed in the Canvas's window title bar to be the specified text.

Args

title
the text to display in the title bar
def set_color(self, obj, color)

Sets the fill and outline color of the specified graphical object. If the object doesn't have one or more of a fill or outline color, setting of that color is ignored.

Args

obj
the object for which to set the color
color
the color to set the fill and outline colors to be, as a string. If this is the empty string, the object will be set to be not filled and not outlined.
def set_fill_color(self, obj, fill_color)

Sets the fill color of the specified graphical object. Cannot be used to change the fill color of non-fillable objects such as images - throws a tkinter.TclError.

Args

obj
the object for which to set the fill color
fill_color
the color to set the fill color to be, as a string. If this is the empty string, the object will be set to be not filled.
def set_font(self, obj, font, size)

Sets the font and size for the text displayed by the given text object. Cannot be used on any non-text graphical object.

Args

obj
the text object for which to set the font and size
font
the name of the font, as a string
size
the size of the font
def set_hidden(self, obj, hidden)

Sets the given graphical object to be either hidden or visible on the canvas.

Args

obj
the graphical object to make hidden or visible on the canvas.
hidden
True if the object should be hidden, False if the object should be visible.
def set_on_button_clicked(self, callback)

Set the specified function to be called whenever a button is clicked. If this function is called multiple times, only the last specified function is called when a button is clicked.

Args

callback
a function to call whenever a button is clicked. Must take in one parameter, which is the text name of the button that was just clicked. E.g. func(button_name). If this parameter is None, no function will be called when a button is clicked.
def set_on_key_pressed(self, callback)

Set the specified function to be called whenever a keyboard key is pressed. If this function is called multiple times, only the last specified function is called when a key is pressed.

Args

callback
a function to call whenever a key is pressed. Must take in one parameter, which is the text name of the key that was just pressed (e.g. 'a' for the a key, 'b' for the b key, etc). E.g. func(key_char). If this parameter is None, no function will be called when a key is pressed.
def set_on_mouse_pressed(self, callback)

Set the specified function to be called whenever the mouse is pressed. If this function is called multiple times, only the last specified function is called when the mouse is pressed.

Args

callback
a function to call whenever the mouse is pressed. Must take in two parameters, which are the x and y coordinates (in that order) of the mouse press that just occurred. E.g. func(x, y). If this parameter is None, no function will be called when the mouse is pressed.
def set_on_mouse_released(self, callback)

Set the specified function to be called whenever the mouse is released. If this function is called multiple times, only the last specified function is called when the mouse is released.

Args

callback
a function to call whenever the mouse is released. Must take in two parameters, which are the x and y coordinates (in that order) of the mouse release that just occurred. E.g. func(x, y). If this parameter is None, no function will be called when the mouse is released.
def set_outline_color(self, obj, outline_color)

Sets the outline color of the specified graphical object. Cannot be used to change the outline color of non-outlined objects such as images or text - throws a tkinter.TclError.

Args

obj
the object for which to set the outline color
outline_color
the color to set the outline color to be, as a string. If this is the empty string, the object will be set to not have an outline.
def set_outline_width(self, obj, width)

Sets the thickness of the outline of the specified graphical object. Cannot be used on objects that are not outline-able, such as images or text.

Args

obj
the object for which to set the outline width
width
the width to set the outline to be.
def set_size(self, obj, width, height)

Sets the width and height of the specified graphical object. Cannot be used to change the size of an image.

Args

obj
the object for which to set the width and height
width
the new width for the object
height
the new height for the object
def set_text(self, obj, text)

Sets the text displayed by the given text object. Cannot be used on any non-text graphical object.

Args

obj
the text object for which to set the displayed text
text
the new text for this graphical object to display
def wait_for_click(self)

Waits until a mouse click occurs, and then returns.