Documentation

A note on notation

In the following documentation, the following syntax is used for method signatures:

func(a, <size>, *, <align>, b, [thickness=0, <color="white">])

This means that:

  • a is a non-optional argument that can be given positionally.
  • <size> means a size-like (more on that later) argument, which can be given positionally.
  • Any arguments after * have to be given using keyword arguments.
  • <align> means an align-like argument that must be given using keyword arguments.
  • b is a keyword-only argument that must be given.
  • If a parameter is inside square brackets, it is optional and a default used if you do not pass it. If an argument is not inside square brackets it must be given, regardless of whether it is keyword-only or not.
  • thickness is a keyword-only argument that is optional, and has default 0.
  • <color> is a color-like argument that is optional, and has default "white".

<x>-like arguments:

  • <position>
    • Can be given as either x and y or position.
    • x and y must be ints or floats.
    • position must be a 2-tuple of ints or floats.
  • <size>
    • Can be given as either width and height or size.
    • width and height must be ints or floats.
    • size must be a 2-tuple of ints or floats.
  • <align>
  • <color>
    • Can be given as either color or r, g, b and optionally a
    • color must either be a color, a str or a 3-tuple of of ints or floats.
    • If color is a str the name is looked up in color.colors and an error raised if it is not found.
    • r, g, b and optionally a must be ints or floats in the range 0-255. a is the transparency.

Constants

left_button
middle_button
right_button

Enumeration representing buttons, used in ClickEvent and is_mouse_pressed().

up_scroll
down_scroll
left_scroll
right_scroll

Enumeration representing scroll directions, used in ScrollEvent.

topleft
topright
bottomleft
bottomright
center

Enumeration representing alignment, use for <align> parameters.

color_names

List of all the color names recognised.

color.colors

A dictionary of color names to colors.

Classes

class image
__init__(fname)
Parameters:fname (str or pathlib.Path) – Path to image file.

Load an image from a file.

Warning

A window must be created before this function is called! A RuntimeError will be raised otherwise.

__init__(<size>, *[, <color="transparent">])

Create a new image of size <size>. If <color> is given, it will be filled with that color, otherwise it will be transparent.

size

Type: 2-tuple of int

The width and height of the image. This attribute is not settable.

width

Type: int

The width of the image. This attribute is not settable.

height

Type: int

The height of the image. This attribute is not settable.

center

Type: 2-tuple of int

The position at the center of the image. This attribute can be used as a <position> or <align>. This attribute is not settable.

topleft

Type: 2-tuple of int

The position at the top-left of the image. This attribute can be used as a <position> or <align>. This attribute is not settable.

topright

Type: 2-tuple of int

The position at the top-right of the image. This attribute can be used as a <position> or <align>. This attribute is not settable.

bottomleft

Type: 2-tuple of int

The position at the bottom-left of the image. This attribute can be used as a <position> or <align>. This attribute is not settable.

bottomright

Type: 2-tuple of int

The position at the bottom-right of the image. This attribute can be used as a <position> or <align>. This attribute is not settable.

copy()
Return type:image

Returns a copy of the image. Changes to the image will not affect the copy.

fill(<color>)
Return type:None

The entire image is set to <color>.

draw_image(source, <position>, *[, <align=topleft>])
Return type:None

Draw source onto this image such that the point on the source indicated by <align> is at <position>. E.g.:

image.draw_image(other, image.bottomright, align=bottomright)

Will draw other onto image such that the bottom-right of other is at the bottom-right of image.

draw_rect(*, <position>, <size>, <color>[, <align=topleft>])
Return type:None

Draw a rectangle of color <color> and size <size> such that <align> is at <position>. The <align> works the same as for draw_image().

draw_hollow_rect(*, <position>, <size>, <color>[, thickness=1, <align=topleft>])
Return type:None

Draw a border of thickness thickness and color <color> in the rectangle defined by <size>, <position> and <align>. The rectangle is defined in the same way as for draw_rect().

draw_circle(*, <position>, <color>, radius)
Return type:None

Draw a circle of color <color> with radius radius with its center at <position>.

draw_hollow_circle(*, <position>, <color>, radius[, thickness=1])
Return type:None

Draw a circular border of color <color> with radius radius and thickness thickness with its center at <position>.

draw_ellipse(*, <position>, <color>, <radii>)
Return type:None

Draw a ellipse of color <color> with radius radius with its center at <position>. Its radii are taken from radii or radius_x and radius_y.

draw_hollow_ellipse(*, <position>, <color>, <radii>[, thickness=1])
Return type:None

Draw a ellipse-shaped border of color <color> with radius radius and thickness thickness with its center at <position>. Its radii are taken from radii or radius_x and radius_y.

draw_line(*, <start>, <end>, <color>[, thickness=1])
Return type:None

Draw a line from <start> to <end> with color <color> and thickness thickness. For <start>, provide start or start_x and start_y. For <end>, provide end or end_x and end_y. <start> and <end> work the same as <position> in every other way.

draw_arc(*, start_angle, end_angle, <position>, <color>, <radii>[, thickness=1])
Return type:None

Draw part of a hollow ellipse defined by <position> and <radii> (see draw_hollow_ellipse()) from start_angle to end_angle clockwise. The angles are in degrees, with 0 being directly above the center of the ellipse.

draw_polygon(points, *, <color>)
Return type:None

Draw a polygon with the vertices in points using <color>.

draw_hollow_polygon(points, *, <color>[, thickness=1])
Return type:None

Draw a hollow polygon with the vertices in points using <color> and thickness thickness.

draw_text(*, text, <position>, <color>[, text, size=30, font=None, bold=False, italic=False, <align=topleft>])
Return type:None

Draw text text in color <color> at <position>. <align> works the same as for draw_rect(). size is the height of the font. If font is None, the default font will be used. Otherwise a font called font will be searched for and a ValueError raised if it cannot be found. bold and italic set the function to use the bold and italic variants of the font.

Note

bold and italic may not work on all fonts, especially the default font. If you cannot see any change when using bold or italic, try changing to a different font.

flip([vertical=False, horizontal=False])
Return type:None

Flip the image vertically if vertical is True and horizontally if horizontal is True.

rotate(angle)
Return type:None

Rotate the image by angle degrees clockwise.

scale(times)
Return type:None

Enlarge the image by factor times. The image will then have a width of times * old_width and a height of times * old_height.

color_at(<position>)
Return type:color

Returns the color of the pixel at <position>

class window

Bases: image

__init__(<size>, *[, <color="white">, frame_rate=20, autoquit=True, title="pygame-go", icon=None])

Create the window with the size <size>. If <color> is given, the window will be filled with that color, otherwise it is filled with white. frame_rate is the number of updates per second, which is controlled during the update() method call. If autoquit is True, then quit events will be processed automatically and active() will return False without any event processing by the user. If autoquit is False, the quit events will be accessible though events(). title will be used to set the window title, see title. icon will be used to set the window icon, see icon.

active()
Return type:bool

Returns whether the window has quit or not. This should be used in your main loop so that your program exits when the user presses the quit button.

stop()
Return type:None

Makes active() return False, stopping the program.

update()
Return type:None

Updates the window, showing the graphics on the window to the user. This function will then delay by the correct amount of time to maintain the correct frame rate.

loop_forever()
Return type:None

Keep updating the window until the user quits. As no event handling can be done in this function, only use it if you only want to show a static image.

has_events()
Return type:bool

Returns True if there are unprocessed events.

next_event()
Return type:Event

Returns the next event to be processed. Raises a ValueError if there are no more events.

events()
Return type:Iterable[Event]

Returns an iterator that yields events in the queue until the queue is empty. This is the preferable way to access events.

title

Type: str

The title of the window. This attribute is settable, and setting a new value will change the window title.

icon

Type: image

The icon of the window, used in the task bar. This attribute is settable, and setting a new value will change the window icon.

Note

May not work with all DEs

class sound
__init__(fname)
Parameters:fname (str or pathlib.Path) – Path to sound file.

Load an sound from a file.

Note

Only .ogg and .wav files can be loaded. This may change in future releases.

play([times=1, forever=False])
Return type:None

Play the sound, repeating it times times. If forever is True, the sound will repeat until stop() is called.

stop()
Return type:None

Stop the sound. This will also unpause the sound.

pause()
Return type:None

Pause the sound if it is not already paused. It can be resumed with unpause().

unpause()
Return type:None

If the sound has been paused, unpause it.

is_playing()
Return type:bool

Returns whether the sound is currently playing.

is_paused()
Return type:bool

Returns whether the sound is currently paused.

length

Type: float

The length of the sound in seconds. This attribute is not settable.

volume

Type: float

The volume of the sound. This attribute can be set in order to change the volume it is played at.

class color
__init__(<color>)

Create a new color.

classmethod fromhex(value)

Create a color from a HTML-style color.

r

Type: int

The red component of the color. It will be in the range 0-255. This attribute is settable.

g

Type: int

The green component of the color. It will be in the range 0-255. This attribute is settable.

b

Type: int

The blue component of the color. It will be in the range 0-255. This attribute is settable.

transparency

Type: int

The transparency component of the color. It will be in the range 0-255. This attribute is settable.

hex

Type: str

The HTML-style hex representation of this color. This attribute is not settable.

class Event

Note

This type should not be created. Rather, use window.events().

is_mouse_press()
Return type:bool

Returns whether this event is a ClickEvent.

is_mouse_scroll()
Return type:bool

Returns whether this event is a ScrollEvent.

is_quit()
Return type:bool

Returns whether this event is a QuitEvent.

is_mouse_motion()
Return type:bool

Returns whether this event is a MotionEvent.

is_key()
Return type:bool

Returns whether this event is a KeyEvent.

class ClickEvent

Bases: Event

Note

This type should not be created. Rather, use window.events().

position

Type: 2-tuple of int

The position of the click.

x

Type: int

The x-coordinate of the click.

y

Type: int

The y-coordinate of the click.

button

Type: One of left_button, right_button or middle_button

The button that was pressed down.

class ScrollEvent

Bases: Event

Note

This type should not be created. Rather, use window.events().

position

Type: 2-tuple of int

The position of the scroll.

x

Type: int

The x-coordinate of the scroll.

y

Type: int

The y-coordinate of the scroll.

direction

Type: One of up_scroll, down_scroll, left_scroll or right_scroll

The direction of the scroll.

class MotionEvent

Bases: Event

Note

This type should not be created. Rather, use window.events().

start

Type: 2-tuple of int

The position the mouse started moving from.

start_x

Type: int

The x-coordinate of start.

start_y

Type: int

The y-coordinate of start.

end

Type: 2-tuple of int

The position the mouse moved to.

end_x

Type: int

The x-coordinate of end.

end_y

Type: int

The y-coordinate of end.

moved_by

Type: 2-tuple of int

The amount of movement in the x and y direction

moved_by_x

Type: int

The amount of movement in the x direction.

moved_by_y

Type: int

The amount of movement in the y direction.

buttons

Type: set containing some of left_button, right_button and middle_button

The buttons that were pressed during the motion. See is_pressed().

is_pressed([button=None)
Return type:bool

If button is one of left_button, right_button or middle_button, returns True if that button was pressed during the motion. If button is None, return True if any buttons were pressed during the motion.

class KeyEvent

Bases: Event

Note

This type should not be created. Rather, use window.events().

key

Type: str

The key that was pressed. It can either be a single ASCII character or a modifier / non-printable key like <Shift> or <Ctrl>. See pygame_go/events.py for the full listing.

class QuitEvent

Bases: Event

Note

This type should not be created. Rather, use window.events().

Other functions

mouse_position()
Return type:2-tuple of int

Returns the current mouse position.

set_mouse_position(<position>)
Return type:None

Sets the current mouse position.

is_key_pressed(key)
Return type:bool

Returns whether the key key is currently pressed. key should be in the same form as for KeyEvent.

is_button_pressed(button)
Return type:bool

Returns whether the button button is currently pressed. button should be one of left_button, right_button or middle_button.

monitor_resolution()
Return type:2-tuple of int

Width and height of the monitor.

collides_rect_rect(*, <position_a>, <size_a>, <align_a>, <position_b>, <size_b>, <align_b>)
Return type:bool

Returns True if the rectangle a defined by <position_a>, <size_a> and <align_a> collides with the rectangle b defined by <position_b>, <size_b> and <align_b>. Arguments follow the above conventions, with _a or _b added on the end.

collides_circle_circle(*, <position_a>, radius_a, <position_b>, radius_b)
Return type:bool

Returns True if the circle a defined by <position_a> and radius_a collides with the rectangle b defined by <position_b>``and ``radius_b. Arguments follow the above conventions, with _a or _b added on the end.