Classes¶

These are the classes returned by simplegui functions. They implement the rest of the simplegui API. The methods on these are responsible for most of the fun stuff that simplegui can do!

Frame¶

class simplequi._frame.Frame(title, canvas_width, canvas_height, control_width=None)¶

Frame that contains all other graphical widgets

Parameters

title (str) – the text to use in the frame title bar
canvas_width (int) – the width of the drawing canvas part of the frame
canvas_height (int) – the height of the drawing canvas part of the frame
control_width (Optional[int]) – the optional width of the controls (buttons etc.) part of the frame

add_button(text, button_handler, width=None)¶

Adds a button to the frame’s control panel with the given text label.

The width of the button defaults to fit the given text, but can be specified in pixels. If the provided width is less than that of the text, the text overflows the button. The handler should be defined with no parameters.

Parameters

text (str) – the button text
button_handler (Callable[[], None]) – a function to call when the button is clicked
width (Optional[int]) – the optional button width

Return type

Control

Returns

a handle that can be used to get and set the button text

add_input(text, input_handler, width)¶

Adds a text input field to the control panel with the given text label.

The input field has the given width in pixels. The handler should be defined with one parameter. This parameter will receive a string of the text input when the user presses the Enter key.

Parameters

text (str) – the text of the input field label
input_handler (Callable[[str], None]) – a function that is called when the user presses enter in the text input field
width (int) – the width of the input field

Return type

Control

Returns

a handle that can be used to get and set the input field text

add_label(text, width=None)¶

Adds a text label to the control panel.

The width of the label defaults to fit the width of the given text, but can be specified in pixels. If the provided width is less than that of the text, the text overflows the label.

Parameters

text (str) – the label text
width (Optional[int]) – the optional label width

Return type

Control

Returns

a handle that can be used to get and set the label text

static get_canvas_textwidth(text, size, face)¶

Given a text string, a font size, and a font face, this returns the width of the text in pixels.

It does not draw the text. This is useful in computing the position to draw text when you want it centered or right justified in some region. The supported font faces are the default ‘serif’, ‘sans-serif’, and ‘monospace’.

Parameters

text (str) – the text to measure
size (int) – the font size that would be drawn with
face (str) – the font face that would be drawn with

Return type

int

Returns

the width of the text in pixels

set_canvas_background(colour)¶

Changes the background colour of the frame’s canvas, which defaults to black.

..seealso:: get_colour() defines the allowed colour definitions

Parameters: colour (str) – the background colour to set, accepts any valid CSS colour
Return type: None

set_draw_handler(draw_handler)¶

Adds an event handler that is responsible for all drawing.

The handler should be defined with one parameter. This parameter will receive a Canvas object.

Parameters: draw_handler (Callable[[Canvas], None]) – function to call every 1/60:sup:th of a second (actually 17ms), which gets a Canvas object as an argument
Return type: None

set_keydown_handler(key_handler)¶

Adds a keyboard event handler waiting for keydown event.

When any key is pressed, the keydown handler is called once. The handler should be defined with one parameter. This parameter will receive an integer representing a keyboard character.

Parameters: key_handler (Callable[[int], None]) – a function to call when a key is pressed down and the frame is focused
Return type: None

set_keyup_handler(key_handler)¶

Adds a keyboard event handler waiting for keyup event.

When any key is released, the keyup handler is called once. The handler should be defined with one parameter. This parameter will receive an integer representing a keyboard character.

Parameters: key_handler (Callable[[int], None]) – a function to call when a key is released and the frame is focused
Return type: None

set_mouseclick_handler(mouse_handler)¶

Adds a mouse event handler waiting for mouseclick event.

When a mouse button is clicked, i.e., pressed and released, the mouseclick handler is called once. The handler should be defined with one parameter. This parameter will receive a pair of screen coordinates, i.e., a tuple of two non-negative integers.

Parameters: mouse_handler (Callable[[tuple], None]) – a function to call when the mouse is clicked
Return type: None

set_mousedrag_handler(mouse_handler)¶

Adds a mouse event handler waiting for mousedrag event.

When a mouse is dragged while the mouse button is being pressed, the mousedrag handler is called for each new mouse position. The handler should be defined with one parameter. This parameter will receive a pair of screen coordinates, i.e., a tuple of two non-negative integers.

Parameters: mouse_handler (Callable[[Tuple[int, int]], None]) – a function to call when the mouse is clicked and dragged
Return type: None

start()¶: Commences event handling on the frame (actually on the canvas that handles the events)

Canvas¶

class simplequi._canvas.Canvas(drawing_area)¶

Wrapper for the drawing area, implementing the codeskulptor canvas API.

This class is passed to the draw_handler set by set_draw_handler() to allow calls to draw on the canvas to be made in draw events. These events occur roughly 60 times per second. Note that users should not create instances of this class, creation is handled internally.

Parameters: drawing_area (DrawingArea) – the actual widget that will be drawn on

draw_arc(center_point, radius, start_angle, end_angle, line_width, line_color, fill_color=None)¶

Draws an arc at the given center point having the given radius.

The point is a 2-element tuple or list of screen coordinates. The starting and ending angles indicate which part of a circle should be drawn. Angles are given in radians, clockwise starting with a zero angle at the 3 o’clock position. The line’s width is given in pixels and must be positive. The fill color defaults to None. If the fill color is specified, then the interior of the circle is colored.

Parameters

center_point (Tuple[int, int]) – the center of the arc
radius (int) – the radius of the arc
start_angle (float) – the start angle of the arc
end_angle (float) – the end angle of the arc
line_width (int) – the line width to draw with
line_color (str) – the line colour to draw with
fill_color (Optional[str]) – the colour to fill the arc with (optional, defaults to transparent)

Return type

None

draw_circle(center_point, radius, line_width, line_color, fill_color=None)¶

Draws a circle at the given center point having the given radius.

The point is a 2-element tuple or list of screen coordinates. The line’s width is given in pixels and must be positive. The fill color defaults to None. If the fill color is specified, then the interior of the circle is colored.

Parameters

center_point (Tuple[int, int]) – the center of the circle
radius (int) – the radius of the circle
line_width (int) – the line width to draw with
line_color (str) – the line colour to draw with
fill_color (Optional[str]) – the colour to fill the circle with, optional, defaults to transparent

Return type

None

draw_image(image, center_source, width_height_source, center_dest, width_height_dest, rotation=0.0)¶

Draw an image that was previously loaded by simplequi.load_image.

center_source is a pair of coordinates giving the position of the center of the image, while center_dest is a pair of screen coordinates specifying where the center of the image should be drawn on the canvas. width_height_source is a pair of integers giving the size of the original image, while width_height_dest is a pair of integers giving the size of how the images should be drawn. The image can be rotated clockwise by rotation radians.

You can draw the whole image file or just part of it. The source information (center_source and width_height_source) specifies which pixels to display. If it attempts to use any pixels outside of the actual file size, then no image will be drawn.

Specifying a different width or height in the destination than in the source will rescale the image.

Parameters

image (Image) – the Image to render
center_source (Tuple[int, int]) – the center point of the portion of the original image to render
width_height_source (Tuple[int, int]) – the width and height of the portion of the original image to render
center_dest (Tuple[int, int]) – the location to render the image on the canvas
width_height_dest (Tuple[int, int]) – the size to render the image on the canvas
rotation (float) – amount in radians to rotate the image, with 0.0 at the 3 o’clock position, increasing clockwise

Return type

None

draw_line(point1, point2, line_width, line_color)¶

Draws a line segment between the two points, each of which is a 2-element tuple or list of screen coordinates. The line’s width is given in pixels and must be positive.

Parameters

point1 (Tuple[int, int]) – the coordinate of the start point of the line
point2 (Tuple[int, int]) – the coordinate of the end point of the line
line_width (int) – the width of the line to draw
line_color (str) – the colour of the line to draw

Return type

None

draw_point(point, color)¶

Draws a 1×1 rectangle at the given point in the given color. The point is a 2-element tuple or list of screen coordinates.

Parameters

point (Tuple[int, int]) – the coordinates of the point
color (str) – the colour to draw the point

Return type

None

draw_polygon(point_list, line_width, line_color, fill_color=None)¶

Draws a sequence of line segments between each adjacent pair of points in the non-empty list, plus a line segment between the first and last points.

It is an error for the list of points to be empty. Each point is a 2-element tuple or list of screen coordinates. The line’s width is given in pixels, and must be positive. The fill color defaults to None. If the fill color is specified, then the interior of the polygon is colored.

Parameters

point_list (Iterable[Tuple[int, int]]) – the coordinates of the polygon’s vertices (the final point is always joined to the first)
line_width (int) – the line width to draw with
line_color (str) – the line colour to draw with
fill_color (Optional[str]) – the colour to fill the polygon with, optional, defaults to transparent

Return type

None

draw_polyline(point_list, line_width, line_color)¶

Draws a sequence of line segments between each adjacent pair of points in the non-empty list.

It is an error for the list of points to be empty. Each point is a 2-element tuple or list of screen coordinates. The line’s width is given in pixels and must be positive.

Parameters

point_list (Iterable[Tuple[int, int]]) – the coordinates of the line’s segment start/finish points, in order
line_width (int) – the line width to draw with
line_color (str) – the line colour to draw with

Return type

None

draw_text(text, point, font_size, font_color, font_face='serif')¶

Writes the given text string in the given font size, color, and font face.

The point is a 2-element tuple or list of screen coordinates representing the lower-left-hand corner of where to write the text. The supported font faces are ‘serif’ (the default), ‘sans-serif’, and ‘monospace’.

Parameters

text (str) – the text to draw
point (Tuple[int, int]) – the point to draw at
font_size (int) – the font size of the text
font_color (str) – the colour of the text
font_face (str) – the font face of the text (one of serif, sans-serif or monospace)

Return type

None

Control¶

class simplequi._widgets.Control(widget)¶

A control that lives in the control area of a Frame, and allows getting and setting of its display text.

Parameters: widget (QWidget) – the widget that this control wraps

get_text()¶

Returns the text in a label, the text label of a button, or the text in the input field of a text input.

For an input field, this is useful to look at the contents of the input field before the user presses Enter.

Return type: str
Returns: the current text of the control

set_text(text)¶

Changes the text in a label, the text label of a button, or the text in the input field of a text input.

For a button, it also resizes the button if the button wasn’t created with a particular width. For an input field, this is useful to provide a default input for the input field.

Parameters: text (str) – the new text to set
Return type: None

Timer¶

class simplequi._timer.Timer(interval, timer_handler)¶

Creates a timer.

Once started, it will repeatedly call the given event handler at the specified interval, which is given in milliseconds. The handler should be defined with no arguments.

Parameters

interval (int) – how often to call the timer_handler
timer_handler (Callable[[], None]) – a function to call every interval milliseconds

is_running()¶

Returns whether the timer is running, i.e., it has been started, but not stopped.

Return type: bool

start()¶: Starts or restarts the timer.

stop()¶: Stops the timer. It can be restarted.

Image¶

class simplequi._image.Image(url)¶

Loads an image from the specified URL.

The image can be in any format supported by PySide2. No error is raised if the file can’t be loaded for any reason, it will simply not draw when asked to.

Parameters: url (str) – the URL to load the image from, can be a local file

get_height()¶: Returns the height of the image in pixels. While the image is still loading, it returns zero.

get_width()¶: Returns the width of the image in pixels. While the image is still loading, it returns zero.

Sound¶

class simplequi._sound.Sound(url)¶

Loads a sound from the specified URL.

Supports whatever audio formats that PySide2 supports (depending on locally-installed codecs). No error is raised if the file isn’t found or is of an unsupported format.

Sounds are tracked

Parameters: url (str) – the URL to load the sound from, can be a local file

pause()¶: Stops the playing of the sound. Playing can be restarted at the stopped point with play().

play()¶: Starts playing a sound, or restarts playing it at the point it was paused.

rewind()¶: Stops playing the sound, makes it so the next play() will start playing the sound at the beginning.

set_volume(volume)¶

Changes the volume for the sound to be the given level on a 0 (silent) – 1.0 (maximum) scale. Default is 1.

Parameters: volume (float) – the volume to set
Return type: None