Window: A Graphics Window

The Basics

The Window is what you use to draw objects on top of and internally, it is an implementation of a Tkinter TopLevel Canvas. It creates a window that you can customize a lot of options with but before we get to that, let us take a look at the basics. Here is how you create a window:

from goopylib.Window import Window  # importing only the Window

window = Window(title="This is a window!", width=500, height=500)

while True:  # This acts as the mainloop
    window.update_win()  # Update the window

This should output a white window with a width & height of 500 pixels. To draw on objects on the Window , we use the draw function which is implemented in every GraphicsObject.

# Place this code before the while loop if you want to draw the Rectangle at the start
# Make sure you import the Rectangle & Point classes
rect = Rectangle(Point(100, 100), Point(400, 400)).draw(window)  # Here, we pass the variable which references the Window

Now, let's try creating a program that detects if the rectangle has been clicked:

# You can edit the mainloop to this
while True:
    mouse_pos = window.check_left_mouse_click()  # Getting the coordinates of a click if one occured
    if rect.is_clicked(mouse_pos): 
        print("Rectangle was Clicked")

    mouse_pos = window.check_mouse_motion() # Gets current mouse position
    if rect.is_clicked(mouse_pos):
        print("Mouse hovering over Rectangle")

---

Window options

The Window has several customizable options which are listed here. You can set these functions while creating the Window like the example shown with the title, width, and height.

1. title - the title of the window (string)

The window dimensions & position are all rounded down to the nearest integer

2. width, height - width & height of the window in pixels (int or float)
3. min_width, min_height - if the window is resizable, the minimum dimensions it can have (int or float)
4. max_width, max_height - if the window is resizable, the maximum dimensions it can have (int or float)
5. resizable_width, resizable_height - is the window resizable? (boolean)
6. x_pos, y_pos - position of the window relative to the top-left of your screen (int or float)
7. style - if a style is assigned, the window attributes will be configured from it. Look at [styles] (To-Do) for more
8. bk_colour - background colour of the window, overrides the style (Colour type, see Colours in Goopy)
9. icon - a .ico file that shows up as the window icon (string, path to the file)

It is recommended that autoflush is False and that you update the window manually as doing otherwise can cause blinking objects when redrawing and other issues.

10. autoflush - does the window update automatically? (boolean)
11. cursor - what should the mouse cursor be inside the window? (string, see Cursors in Goopy)
12. border_relief - the relief of the window border (string, see [Relief List] (To-Do))
13. border_width - width of the border in pixels (integer or float)

Window Functions List

This is a list of all the functions in the Window.

Important Functions

1. close() - Closes the window
2. update_win() - Updates the window
3. is_closed() - Checks if the window is closed
4. is_open() - Checks if the window is open
5. clear() - Clears the window
6. redraw() - Redraws everything on the window

Mouse & Keyboard Functions

These functions allow you to take input from the user and are in the format

check_{mousebutton}_mouse_{type}() 
# and 
get_{mousebutton}_mouse_{type}()

This is the general format for mouse event functions and they each return a Point object Point(mouse_x, mouse_y) with the coordinates of the event. mousebutton can be anyone of left, right, and middle while {type} can be either click or press.

To check/get double or triple mouse events, the format changes to check_{clicks}_{mousebutton}_mouse_{type}() and get_{clicks}_{mousebutton}_mouse_{type}() where {clicks} can be either double or triple.

For example: check_left_mouse_click(), get_middle_mouse_press(), etc.

The difference between the get and check variants is that getting waits until an event occurs whereas check returns a None value if no event has occurred.

There are a few other functions too

1. check_mouse_scroll() - Gets the value of the mouse scroll wheel
2. get_last_mouse() - Gets the location of the last event
3. check_mouse_motion() - Gets the location of the mouse if it has moved
4. check_left_mouse_down() - left can be replaced with either middle or right. This returns True if the mouse button is being held and False otherwise.

The Keyboard functions do not currently work and so they are not included here right now.

Movement Functions

The dx, dy, x, y, & time values are all integers or floats (internally rounded down except for time). All of these functions return self, i.e. the window object itself.

1. move(dx, dy) - Moves the window by dx, dy
2. move_x(dx) - Moves the window by dx
3. move_y(dy) - Moves the window by dy
4. move_to(x, y) - Moves the window to the specified location
5. move_to_x(x) - Moves the window to the X location
6. move_to_y(y) - Moves the window to the Y location
7. move_to_point(p) - Moves the window to the Point specified as Point(x, y)

Gliding Functions

Gliding functions move the window to a location over a period of time rather than just instantly. The time & easing arguments for these functions need not be provided as they default to 1 and ease_linear() respectively.

For more information about easing functions, see [Easing in Goopy] (To-Do). These functions return the window object too.

1. glide(dx, dy, time, easing_x, easing_y) - Moves the window by dx, dy
2. glide_x(dx, time, easing) - Moves the window by dx
3. glide_y(dy, time, easing) - Moves the window by dy
4. glide_to(x, y, time, easing_x, easing_y) - Moves the window to the specified location
5. glide_to_x(x, time, easing) - Moves the window to the X location
6. glide_to_y(y, time, easing) - Moves the window to the Y location
7. glide_to_point(p, time, easing_x, easing_y) - Moves the window to the Point specified as Point(x, y)

Getting Window Attributes

1. get_window_pos() - Returns the position of the window relative to the top-left of the screen as a Point(x, y) object
2. get_bk_colour() - Returns the background colour of the window as a Colour object
3. get_size(), get_width(), get_height() - Return the size (width, height) of the window in pixels
4. get_min_size(), get_min_width(), get_min_height()
5. get_max_size(), get_max_width(), get_max_height()
6. is_resizable(), is_width_resizable(), is_height_resizable() - Return a boolean value
7. get_border_width(), get_border_relief()
8. get_cursor()
9. get_title()
10. get_coords - Returns the window coordinates Point(topleft), Point(bottomright)

Setting Window Attributes

These are all pretty self-explanatory and the inputs arguments are the same as those in the options.

1. set_background(colour)
2. set_border_width(width)
3. set_border_relief(relief)
4. set_cursor(cursor)

These resizable values are True by default

5. set_resizable(resizable_width, resizable_height)
6. set_resizable_width(resizable_width)
7. set_resizable_height(resizable_height)

8. set_icon(icon)
9. set_title(title)
10. set_width(width)
11. set_height(height)
12. set_min_height(min_height)
13. set_min_width(min_width)
14. set_size(width, height)
15. set_min_size(min_width, min_height)
16. set_max_size(max_width, max_height)
17. set_max_width(max_width)
18. set_max_height(max_height)
19. set_coords(x1, y1, x2, y2) - This sets the virtual coordinates of the window from top-left (x1, y1) to bottom-right (x2-y2) without affecting the actual coordinates. This can be used to move the view of the window around, make this value a constant, etc. You can also stretch the window through this though it is not recommended as text & entries won't undergo the stretch.

Misc Functions

1. plot(x, y, colour) - Plots a pixel at x, y with a colour (defaults to BLACK)
2. flush() - Updates the drawing on the window (not recommended, use update_win() instead)
3. update() - Updates the window (not recommended, use update_win() instead)
4. save_canvas() - Saves a snapshot of the window (doesn't work properly yet)

Undraw & Destroy Functions

These functions undraw specific/all the graphics objects present on the window.

1. undraw_all()
2. undraw_all_instances(obj) - Undraws all objects which are the same type as that of obj
3. undraw_all_lines()
4. undraw_all_circles()
5. undraw_all_rectangles()
6. undraw_all_ovals()
7. undraw_all_images()

These functions destroy specific/all objects on the window.

1. destroy_all()
2. destroy_all_instances(obj)
3. destroy_all_lines()
4. destroy_all_circles()
5. destroy_all_rectangles()
6. destroy_all_ovals()
7. destroy_all_images()

Autoflush in the Window

It is recommended that the autoflush parameter of the Window is False and we can demonstrate why using a simple example:

from goopylib.imports import *

window = Window(title="This is a window!", width=500, height=500)  # Autoflush defaults to True

rect = Rectangle(Point(10, 230), Point(50, 270)).draw(window)
rect.glide(dx=200, time=2) # This makes the Rectangle slowly move across the screen 200 pixels in 2 seconds

while True:
    update(24)

Now compare this code to

from goopylib.imports import *

window = Window(title="This is a window!", width=500, height=500, autoflush=False)

rect = Rectangle(Point(10, 230), Point(50, 270)).draw(window)
rect.glide_x(dx=200, time=2) # This makes the Rectangle slowly move across the screen horizontally (x) 200 pixels in 2 seconds

while True:
    window.update_win()  # Updating the window manually
    update(24)  

You will notice that in the first example, the Rectangle will tend to well.. not move unless you move your mouse over the window, click it, or something else that triggers the window updating. This is in stark contrast to the second example where the motion of the rectangle is very fluid.

Sometimes, when drawing objects and moving them manually (not through the glide function but the move function) the objects will tend to flicker if autoflush is off because the window is updating both when the object undraws, and also when it draws itself again.