Welcome to JGUVC_EIP’s documentation!

The jguvc_eip module provides some library functions for the lecture “Einführung in die Programmierung” (Introduction to Programming) held in the summer semester of 2022 (and onwards). The main piece of functionality is a module called basic_io that allows the user to output graphics directly to a window, without resorting to event-based programming (which is difficult to grasp for beginners). Vaguely, the goal is to make graphics programming as easy as on some beginner programming tools for the early home computers (such as Simons Basic, AMOS, Quick-Basic or the similar).

The motivation is two-fold: First, graphics can be more intuitive and motivating than simple console-io (such as the infamous bubble-sort of an array of numbers as the “standard” programming assignment in the first-year course). Second, in some instances of the “EIP” course, the programming language PyRet (https://www.pyret.org/) is used, which provide similar functionality in its build in ‘image’ module (see https://www.pyret.org/docs/latest/image.html). When teaching a “pure-python” version of the course, this library is not available, so the basic_io package has been devised as a substitute.

Imports:

The package can be imported via:

from jguvc_eip import basic_io     # basic_io package - provides input and output commands
from jguvc_eip.colors import *     # [optional] some predefined colors like RED, GREEN, BLUE, BLACK, WHITE
import jguvc_eip.image_objects     # [optional] the object oriented interface

Session Management:

After importing the basic_io subpackage, you can open a window where all the content is shown by calling:

basic_io.start()

This should be the first instruction in your program. If you forget to call start, the first basic_io operation performed will automatically call start(); however, this is considered unclean (and the window will not show up until the first i/o-instruction is reached).

If you want this window to persist after your application terminates (so you have to close the window manually), end your program with the instruction:

basic_io.wait_close()    # waits until the user closes the window

Input/Output: Drawing Graphics and Interacting with the User

The library provides two different modes of operation:

  • Imperative, immediate mode input & output

  • Object oriented output with tree-structured graphics objects.

The first mode of operation is very simple.

You can just write:

basic_io.draw_circle(100, 100, 50, RED)

in order to draw a red circle on the screen (centered around pixel x=100, y=100 and with radius 50. If you want to try it out, do not forget to add basic_io.wait_close() after the drawing command (otherwise, the window is gone immediately after the python script finishes executing).

Similarly, you can query input devices “live” (without event processing) by simple commands like:

keys = basic_io.get_current_keys_down()
mouse_pos = basic_io.get_current_mouse_position

The first command returns a list with all keys pressed on the keyboard at the moment the function has been called. The second returns the mouse coordinates (if the mouse is over the output window).

The object-oriented drawing commands take composite objects that describe complex shapes as a tree (nested structure) of elementary operations. This mimics the interface in PyRet and could have some didactic value in understanding composite data types and functional programming concepts (as each object represents an action take taken at a later time).

Object-oriented drawing is always performed via:

basic_io.draw_object(some_image_object)

where the parameter of the function is an image object. Various image objects are provided in the module image_objects.

A simple example could look like this:

basic_io.draw_object(image_objects.Circle(50, RED))

This command draws a red circle on the screen - it does the same as the immediate-mode operation above, just written differently (and without center coordinates). The advantage of the OO-interface becomes apparent when using more complex, composite shapes, such as:

basic_io.draw_object(
  image_objects.VerticalStack([
     image_objects.Text("-- French Flag --", bold=True),
     image_objects.Rectangle(350, 80, RED, None),
     image_objects.Rectangle(350, 80, WHITE, None),
     image_objects.Rectangle(350, 80, BLUE, None)
  ])
)

This command draws a frensh flag with some text on top to describe it.

Quick Reference

For details, see the module reference.

The documentation of module basic_io (link) lists all of the available input and output functions. Please consult image_objects (link) for a list of available objects. Some symbolic names for colors are provided in the colors (link) module. basic_io_error (link) provides a simple exception class. Other submodules of the package are internal and should not be used from the outside from your application.

Module Basic-IO (basic_io)

Detailed documentation: jguvc_eip.basic_io

This is the main piece - it lets you input and output stuff to the io-window.

Session management:

  • start(): This function opens the io window and we can start interacting with it. This should be the first statement in your code.

  • wait_close(): This command waits until the window is closed.

  • close_and_exit(): Closes the io window and exits the main process, too (stops the currently running program immediately).

Drawing functions

  • draw_line(): Draw a line on the currently active image.

  • draw_circle(): Draw a circle on the currently active image.

  • draw_ellipse(): Draw an axis-aligned ellipse on the currently active image.

  • draw_rectangle(): Draw a rectangle on the currently active image.

  • draw_polygon(): Draw a polygon on the currently active image.

  • draw_text(): Draws text at an arbitrary position on the currently active image.

  • draw_pixel(): Changes the color of a single pixel in the active buffer

Read from screen

  • read_pixel(): Reads the color of the specified pixel from the active buffer.

Support for Sprites/Icons

  • load_image(): Loads an image into an internal image database from an external file.

  • draw_image(): Draws an image to the screen (more precisely, the active buffer).

Object-oriented drawing

  • draw_object(): Draws a (potentially complex/composite) image object onto the screen.

Frame-buffer Management:

  • clear_image(): This image clears the active image, overwriting all pixels with a fixed color.

  • set_active_image(): This command chooses which image the draw commands are directed to (which image to draw on).

  • set_visible_image(): This command chooses which image is currently visible.

  • copy_image(): This command copies the content of an image from one buffer to another.

  • resize_image(): This image clears the active image, overwriting all pixels with a fixed color.

Input functions:

  • get_last_key_pressed_event(): This function handles “buffered” keyboard input

  • clear_key_pressed_event_buffer(): Clears the buffer of all key press events recorded so far.

  • get_current_keys_down(): This function handles “unbuffered” keyboard input.

  • get_current_mouse_position(): Queries the current mouse position.

Build-in console window:

  • print_message(): Prints a message on the message console of the basic_io window (default: lower part of the window),

  • print_html(): Prints a message on the message console of the basic_io window (default: lower part of the window),

  • input_string(): This command opens a small edit box and asks for text to be entered. The result is returned as a string.

Module Image Objects (image_objects)

Detailed documentation: jguvc_eip.image_objects

This submodule provides different graphics objects

  • ImageObject Super Class of all image objects - do not use directly

  • Rectangle: This class represents/draws a rectangle with specified width and height.

  • Circle: This class represents/draws a circle with specified radius

  • Ellipse: This class represents/draws an ellipse with axis-aligned diameters “width” and “height”

  • Polygon: This class represents/draws a polygon consisting of a list of points.

  • Text: This class represents/draws text specified by a string.

  • VerticalStack: This class stores a list of image objects that are stacked vertically on top of each other

  • HorizontalStack: This class stores a list of image objects that are stacked horizontally next to each other

  • Overlay: This class stores a list of image objects drawn over each other. The first object in the list is drawn

  • Translate: This class is a container that translates (shifts in space) the position of the contained object.

  • Scale: This class is a container that scales the contained object (changes its size by a factor)

  • Rotate: This class is a container that rotates the contained object counterclockwise

License

The whole package is open source, licensed under the MIT license - see license.txt for details.

Indices and tables