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_new_mouse_drag_events(self)

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

Returns

a list of all mouse drag events that have occurred since the last call to this function or any registered mouse handler. Each mouse drag event contains x and y properties for the drag location, e.g. mouse_drag_events = canvas.get_new_mouse_drag_events(); print(mouse_drag_events[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)

Same as Canvas.moveto().

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_dragged(self, callback)

Set the specified function to be called whenever the mouse is dragged (moved while held down). If this function is called multiple times, only the last specified function is called when the mouse is dragged.

Args

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

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.